# ECS deployment circuit breaker

AWS configuration · Updated 17 November 2026

**Short answer:** The deployment circuit breaker watches an ECS rolling deployment and marks it FAILED when too many tasks fail to start or fail health checks; with rollback enabled, ECS then redeploys the last COMPLETED revision. It is off unless you enable it. By default the failure threshold is half the desired count, clamped between 3 and 200 (BOUNDED_PERCENT, value 50), and consecutive failures reset when a task becomes healthy. You can now set a fixed COUNT or UNBOUNDED_PERCENT threshold and cumulative counting. Enable it with rollback on every rolling-update service.

## How it decides a deployment failed

The circuit breaker only applies to the rolling update (`ECS`) deployment controller. It works in two stages:

1. **Tasks reaching RUNNING.** Tasks that fail to start (image pull errors, bad configuration, crash at launch) count as failures.
2. **Health checks.** Once at least one task is running, tasks replaced because they failed ELB, Cloud Map or container health checks count as failures.

When failures reach the threshold the deployment's `rolloutState` becomes `FAILED`, ECS stops launching tasks for it and sends a `SERVICE_DEPLOYMENT_FAILED` event to EventBridge. With `rollback=true` it starts a new deployment of the last revision in the COMPLETED state. If there is no completed deployment to roll back to (for example the previous rollback is itself still in progress), the deployment stalls.

## Settings

| Setting | Default | Options |
|---|---|---|
| `enable` | false (circuit breaker off) | true / false |
| `rollback` | - | true / false |
| `thresholdConfiguration.type` | BOUNDED_PERCENT | BOUNDED_PERCENT, UNBOUNDED_PERCENT, COUNT |
| `thresholdConfiguration.value` | 50 | 1 to 100 for percentage types; a count for COUNT |
| `resetOnHealthyTask` | true (only consecutive failures count) | false = every failure accumulates |

With the default type the threshold is `ceil(value/100 x desired count)`, at least 3 and at most 200. So a service of 4 tasks fails after 3 failures, 25 tasks after 13, and 400 tasks after 200.

## Recommended configuration

| Service | Suggested setting |
|---|---|
| Most production services | enable, rollback, defaults |
| Small services (1 to 6 tasks) where you want faster rollback | COUNT with value 2 or 3 |
| Large fleets where 200 failures is too many | UNBOUNDED_PERCENT with a lower value, or COUNT |
| Apps with flaky first starts that recover | Keep resetOnHealthyTask true |
| Apps where any repeated failure means a bad release | resetOnHealthyTask false |

Pair it with a realistic [health check grace period](https://cloudconsole.dev/config/ecs-health-check-grace-period); otherwise slow-starting tasks look like failures and the breaker rolls back a good release. For alarm-driven rollback (errors or latency after tasks are healthy), add the deployment `alarms` option as well.

## Change it

```
# Enable with rollback and defaults
aws ecs update-service --cluster prod --service orders-api \
  --deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true},maximumPercent=200,minimumHealthyPercent=100"

# Fixed threshold of 3 failures, counted cumulatively
aws ecs update-service --cluster prod --service orders-api \
  --deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true,resetOnHealthyTask=false,thresholdConfiguration={type=COUNT,value=3}}"

# Watch the rollout
aws ecs describe-services --cluster prod --services orders-api \
  --query 'services[0].deployments[].{status:status,rollout:rolloutState,reason:rolloutStateReason,running:runningCount,failed:failedTasks}'
```

Include `maximumPercent` and `minimumHealthyPercent` in the same structure so the values you rely on are explicit in every update.

**CloudFormation:** `DeploymentConfiguration` > `DeploymentCircuitBreaker` on `AWS::ECS::Service`, with `Enable`, `Rollback`, `ResetOnHealthyTask` and `ThresholdConfiguration`. **Terraform:** `deployment_circuit_breaker { enable = true, rollback = true }` on `aws_ecs_service`.

## Symptoms and gotchas

- **Stack updates fail with "ECS Deployment Circuit Breaker was triggered"**: CloudFormation reports the ECS failure and rolls the stack back. Look at the service events and the stopped tasks' reasons for the real cause.
- **Rollback then nothing:** a second failed deploy while the rollback is IN_PROGRESS has no COMPLETED deployment to return to and stalls.
- **No rollback with CodeDeploy blue/green or external controllers:** the breaker doesn't apply; use CodeDeploy's own rollback.
- **Slow detection on big services:** with the default type, a 400-task service tolerates 200 failures; lower it.

## Questions

### Is the ECS deployment circuit breaker enabled by default?

No. You must set deploymentCircuitBreaker enable=true on the service, ideally with rollback=true.

### What is the ECS circuit breaker failure threshold?

By default half the desired task count, rounded up, with a minimum of 3 and a maximum of 200. You can change it with thresholdConfiguration.

### Why did my ECS deployment circuit breaker trigger?

Tasks repeatedly failed to reach RUNNING or failed health checks. Check stopped task reasons with aws ecs describe-tasks and the service events.

## When this happens away from your desk

A rollback that happens at 2am is only useful if someone finds out why. CloudConsole, a phone app for AWS, is being built to show ECS deployment events 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

- [How the Amazon ECS deployment circuit breaker detects failures](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-circuit-breaker.html)
- [AWS::ECS::Service DeploymentCircuitBreaker](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-ecs-service-deploymentcircuitbreaker.html)

## Related

- [ECS health check grace period](https://cloudconsole.dev/config/ecs-health-check-grace-period)
- [ECS minimum healthy percent and maximum percent](https://cloudconsole.dev/config/ecs-minimum-healthy-percent)
- [Task failed ELB health checks in target group](https://cloudconsole.dev/errors/ecs-task-failed-elb-health-checks)
- [aws ecs update-service](https://cloudconsole.dev/cli/ecs-update-service)
- [aws ecs describe-services](https://cloudconsole.dev/cli/ecs-describe-services)
- [AWS ECS force new deployment](https://cloudconsole.dev/how-to/force-new-deployment-ecs)
- [ECS deployment failed: Deployment Circuit Breaker was triggered](https://cloudconsole.dev/errors/ecs-deployment-circuit-breaker)

---

Source: https://cloudconsole.dev/config/ecs-deployment-circuit-breaker

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