# Target group deregistration delay (connection draining)

AWS configuration · Updated 17 November 2026

**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.

## 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

| Workload | Deregistration delay | Why |
|---|---|---|
| HTTP APIs with fast requests (under 1 to 2 s) | 15 to 30 s | Long enough for in-flight requests, short deploys |
| Web apps with some slow requests or uploads | 60 to 120 s | Cover the slowest normal request |
| WebSockets or long-polling | Match how long you can let clients stay before forcing reconnection | Connections stay until the delay ends |
| Batch-style or long downloads through the ALB | Up to 3,600 s | Only if requests truly last that long |
| NLB with long-lived TCP | As needed; consider `deregistration_delay.connection_termination.enabled` | Closes 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](https://cloudconsole.dev/errors/ecs-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](https://cloudconsole.dev/config/ecs-minimum-healthy-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 CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Edit target group attributes for your Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/edit-target-group-attributes.html)
- [TargetGroupAttribute (ELB API reference)](https://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference/API_TargetGroupAttribute.html)

## Related

- [ALB target group health check settings](https://cloudconsole.dev/config/target-group-health-check-settings)
- [ALB idle timeout and HTTP client keepalive duration](https://cloudconsole.dev/config/alb-idle-timeout)
- [ECS minimum healthy percent and maximum percent](https://cloudconsole.dev/config/ecs-minimum-healthy-percent)
- [ECS container exited with exit code 143 (SIGTERM)](https://cloudconsole.dev/errors/ecs-exit-code-143)
- [AWS ECS force new deployment](https://cloudconsole.dev/how-to/force-new-deployment-ecs)
- [ALB 502 Bad Gateway](https://cloudconsole.dev/errors/alb-502-bad-gateway)

---

Source: https://cloudconsole.dev/config/deregistration-delay

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
