# ECS health check grace period

AWS configuration · Updated 17 November 2026

**Short answer:** The health check grace period (healthCheckGracePeriodSeconds) is how long the ECS service scheduler ignores failing Elastic Load Balancing, VPC Lattice and container health checks after a task starts. It defaults to 0, so a slow-starting app can be killed and replaced in a loop before it ever becomes healthy. Set it to roughly your worst-case start-up time plus one or two health check intervals, typically 60 to 180 seconds for JVM or large apps; it doesn't trigger a new deployment when changed.

## What it does and doesn't cover

During the grace period the scheduler won't stop a task because the target group or the container `healthCheck` reports it unhealthy. After it ends, normal rules apply: the task is replaced once the target group marks it unhealthy or the container health check fails its retries.

What it doesn't do:

- It doesn't delay the load balancer's own checks or routing. The target group still checks the task and only routes traffic once it passes.
- It doesn't help a container that crashes or exits; that's a different failure ([essential container exited](https://cloudconsole.dev/errors/ecs-essential-container-exited)).
- If the service uses no health checks at all, the setting is unused.

The maximum is 2,147,483,647 seconds, but very long values hide genuinely broken tasks for that long.

## Choosing a value

Measure how long a task takes from RUNNING to answering its health endpoint (application logs, or time from task start to the target becoming healthy in `describe-target-health`), then:

grace period = worst-case start-up + (healthy threshold x health check interval)

| App | Typical start-up | Suggested grace period |
|---|---|---|
| Go, Node.js, small Python service | 2 to 15 s | 30 to 60 s |
| Spring Boot / JVM | 30 to 90 s | 120 to 180 s |
| App that warms caches or runs migrations at start | Minutes | Fix the start-up first; then up to 300 s |

Container health checks have their own `startPeriod` (0 to 300 seconds) in the task definition; failures during that period don't count against retries. Use both: `startPeriod` for the container check and the service grace period for load balancer checks.

## Change it

**CLI** (applies to new tasks without a new deployment):

```
aws ecs update-service --cluster prod --service orders-api --health-check-grace-period-seconds 120

aws ecs describe-services --cluster prod --services orders-api \
  --query 'services[0].{grace:healthCheckGracePeriodSeconds,events:events[:5].message}'
```

**Console:** ECS, cluster, service, **Update**, then **Health check grace period** in the load balancing section.

**CloudFormation:** `HealthCheckGracePeriodSeconds` on `AWS::ECS::Service`. **Terraform:** `health_check_grace_period_seconds` on `aws_ecs_service`.

## Symptoms of getting it wrong

| Symptom | Likely setting |
|---|---|
| Service events repeat "(task ...) failed ELB health checks" and tasks restart every minute or two after a deploy | Grace period 0 or shorter than start-up |
| Deployment circuit breaker rolls back a release that works fine locally | Same: tasks killed before ready |
| A broken release stays "running" for many minutes before being replaced | Grace period much longer than needed |
| Tasks are healthy but get no traffic for a while | Target group healthy threshold x interval, not the grace period |

When tasks loop, check the stopped task's reason: `Task failed ELB health checks in (target-group ...)` points to this setting or the [health check settings](https://cloudconsole.dev/config/target-group-health-check-settings); see [ECS failed ELB health checks](https://cloudconsole.dev/errors/ecs-task-failed-elb-health-checks).

## Questions

### What is the default ECS health check grace period?

0 seconds. Without a value, ECS acts on failed load balancer and container health checks as soon as a task starts.

### Does changing the health check grace period redeploy the service?

No. Updating healthCheckGracePeriodSeconds doesn't start a new deployment; it applies to tasks launched afterwards.

### How do I set the ECS health check grace period in Terraform?

Use health_check_grace_period_seconds on the aws_ecs_service resource.

## When this happens away from your desk

Start-up kill loops typically show up as a deploy that never finishes. CloudConsole, a phone app for AWS, is being built to show ECS service events and alarms on your phone so you can spot the loop early.

[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

- [Amazon ECS service definition parameters](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service_definition_parameters.html)
- [AWS::ECS::Service](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ecs-service.html)

## Related

- [Task failed ELB health checks in target group](https://cloudconsole.dev/errors/ecs-task-failed-elb-health-checks)
- [ALB target group health check settings](https://cloudconsole.dev/config/target-group-health-check-settings)
- [ECS deployment circuit breaker](https://cloudconsole.dev/config/ecs-deployment-circuit-breaker)
- [ECS minimum healthy percent and maximum percent](https://cloudconsole.dev/config/ecs-minimum-healthy-percent)
- [aws ecs update-service](https://cloudconsole.dev/cli/ecs-update-service)
- [Essential container in task exited](https://cloudconsole.dev/errors/ecs-essential-container-exited)

---

Source: https://cloudconsole.dev/config/ecs-health-check-grace-period

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