CloudConsole

Target group deregistration delay (connection draining)

Updated 17 November 2026 · How we write and check guides

Short answer

Deregistration delay (deregistration_delay.timeout_seconds) is how long an ALB or NLB keeps a deregistering target in the draining state so in-flight requests can finish: 300 seconds by default, 0 to 3,600 allowed. New requests stop going to the target immediately. For typical HTTP APIs with sub-second requests, 15 to 60 seconds makes ECS deployments and scale-in much faster; keep it longer than your slowest request, and make sure the task or instance doesn't exit before the delay ends.

Timeline: What happens when a target is deregistered. New requests to the target: stop immediately; Draining, default…
Where this setting acts, with the default and allowed values from this page.

What happens during deregistration

  1. The target is deregistered: by ECS stopping a task, Auto Scaling terminating an instance, or you calling deregister-targets.
  2. The load balancer stops routing new requests to it straight away; the target shows draining.
  3. Existing connections and in-flight requests carry on until they finish or the delay expires.
  4. When the delay ends the target becomes unused and the ALB closes anything still open. If a target with no active connections finishes early, deregistration completes at once, although the console may keep showing draining until the timeout.

If the target itself shuts down before draining finishes, clients with open requests get 5xx errors. That is the usual source of 502s during deploys.

Recommended values

WorkloadDeregistration delayWhy
HTTP APIs with fast requests (under 1 to 2 s)15 to 30 sLong enough for in-flight requests, short deploys
Web apps with some slow requests or uploads60 to 120 sCover the slowest normal request
WebSockets or long-pollingMatch how long you can let clients stay before forcing reconnectionConnections stay until the delay ends
Batch-style or long downloads through the ALBUp to 3,600 sOnly if requests truly last that long
NLB with long-lived TCPAs needed; consider deregistration_delay.connection_termination.enabledCloses connections at the end of the delay

Lambda targets don't use this attribute.

Line it up with how the target stops

For ECS, the sequence on a deploy is: deregister from the target group, wait for draining, then send SIGTERM to the container, wait stopTimeout (30 seconds by default on Fargate), then SIGKILL. So:

  • The app should keep serving during draining and handle SIGTERM by finishing in-flight work, then exiting. Exit code 143 is a SIGTERM exit; see exit code 143.
  • For EC2 Auto Scaling, use a termination lifecycle hook if instances need more time than the delay.
  • A very long delay multiplied by many tasks and a low maximum percent makes deployments crawl.

Change it

CLI:

aws elbv2 modify-target-group-attributes \
  --target-group-arn arn:aws:elasticloadbalancing:eu-west-2:123456789012:targetgroup/api/73e2d6bc24d8a067 \
  --attributes Key=deregistration_delay.timeout_seconds,Value=30

aws elbv2 describe-target-group-attributes \
  --target-group-arn arn:aws:elasticloadbalancing:eu-west-2:123456789012:targetgroup/api/73e2d6bc24d8a067 \
  --query "Attributes[?starts_with(Key,'deregistration_delay')]"

Console: EC2, Target Groups, select the group, Attributes, Edit, Deregistration delay.

CloudFormation: on AWS::ElasticLoadBalancingV2::TargetGroup, under TargetGroupAttributes:

TargetGroupAttributes:
  - Key: deregistration_delay.timeout_seconds
    Value: "30"

Terraform: deregistration_delay on aws_lb_target_group (default 300).

Symptoms of a wrong value

  • Deploys and scale-in take ages, with tasks in DEACTIVATING or "draining" for five minutes: the default 300 seconds is far longer than your requests.
  • 502s or connection resets during deploys: the app exits before draining ends, or the delay is shorter than real request times.
  • Long-lived connections cut at a fixed time after deploy: that is the delay ending; extend it or make clients reconnect gracefully.

Questions

What is the default deregistration delay?

300 seconds. The valid range is 0 to 3,600 seconds.

Does deregistration delay affect ECS deployments?

Yes. ECS waits for draining to finish before stopping old tasks, so the delay adds directly to deployment and scale-in time.

What does draining mean in a target group?

The target has been deregistered: it receives no new requests, but existing ones can complete until the deregistration delay expires.

When this happens away from your desk

A slow deploy at night is often just a five-minute default drain multiplied by every task. CloudConsole, a phone app for AWS, is being built to show ECS deployment progress and alarms on your phone.

About the app → · Download on the App Store

Sources