CloudConsole

ECS health check grace period

Updated 17 November 2026 · How we write and check guides

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.

Timeline: When health check failures start to count. App start-up (example: 90 s): starting, healthy; Grace period 0 s…
Where this setting acts, with the default and allowed values from this page.

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).
  • 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)

AppTypical start-upSuggested grace period
Go, Node.js, small Python service2 to 15 s30 to 60 s
Spring Boot / JVM30 to 90 s120 to 180 s
App that warms caches or runs migrations at startMinutesFix 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

SymptomLikely setting
Service events repeat "(task ...) failed ELB health checks" and tasks restart every minute or two after a deployGrace period 0 or shorter than start-up
Deployment circuit breaker rolls back a release that works fine locallySame: tasks killed before ready
A broken release stays "running" for many minutes before being replacedGrace period much longer than needed
Tasks are healthy but get no traffic for a whileTarget 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; see ECS 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 app → · Download on the App Store

Sources