# aws ecs stop-task

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws ecs stop-task --cluster my-cluster --task <task-id> --reason "stuck worker" stops a running task. ECS sends SIGTERM, waits for the container's stop timeout (30 seconds by default), then sends SIGKILL. If the task belongs to a service, the service starts a replacement, so stop-task effectively restarts that one task.

## What the command does

The call sets the task's desired status to `STOPPED`. ECS then signals each container: `SIGTERM` first, giving the process a chance to finish requests and close connections, and `SIGKILL` once the stop timeout expires. The task's `stopCode` becomes `UserInitiated`, and the text you pass in `--reason` shows up as `stoppedReason`, which helps the next person reading `describe-tasks`.

## Syntax

```
aws ecs stop-task --cluster my-cluster --task <task-id-or-arn> [--reason "text"]
```

Only one task per call. The response is the task description at the moment of the request, usually still showing `lastStatus: RUNNING` with `desiredStatus: STOPPED`.

## Worked examples

**Replace one unhealthy task of a service** with a recorded reason:

```
aws ecs stop-task --cluster prod --task 0123456789abcdef0123456789abcdef \
  --reason "high memory, replaced by on-call" \
  --query "task.[lastStatus,desiredStatus]" --output text
```

**Stop it and wait until it has actually stopped**, then read the exit code:

```
aws ecs stop-task --cluster prod --task "$TASK"
aws ecs wait tasks-stopped --cluster prod --tasks "$TASK"
aws ecs describe-tasks --cluster prod --tasks "$TASK" \
  --query "tasks[0].containers[].[name,exitCode]" --output text
```

**Stop every task started by a runaway job**:

```
for t in $(aws ecs list-tasks --cluster batch --started-by nightly-report \
    --query "taskArns[]" --output text); do
  aws ecs stop-task --cluster batch --task "$t" --reason "cancelled runaway job" >/dev/null
done
```

**Stop all tasks of a service without them coming back**: scale the service instead of stopping tasks:

```
aws ecs update-service --cluster prod --service orders-api --desired-count 0
```

## Exit codes after a stop

| Exit code | What happened |
|---|---|
| 0 | The process caught SIGTERM and exited cleanly. |
| 143 | The process was terminated by SIGTERM without handling it (128 + 15). Usually harmless. |
| 137 | The process ignored SIGTERM and was killed with SIGKILL after the stop timeout (128 + 9), or ran out of memory. |

Exit 137 on every stop usually means the application is PID 1 in the container and does not forward signals, often because a shell script wraps it. Use `exec` in the entrypoint script or enable an init process in the task definition.

## Gotchas

- **Services replace stopped tasks.** That is fine for "restart this one task", but stopping tasks will not shrink or stop a service.
- **The stop timeout is per container.** Set `stopTimeout` in the container definition if your app needs longer to drain; Fargate caps it at 120 seconds.
- **Load balancer draining** happens in parallel. If the deregistration delay is longer than the stop timeout, in-flight requests can still be cut off.
- **Who stopped my task?** CloudTrail records `StopTask` with the caller; tasks stopped by the service scheduler itself show `ServiceSchedulerInitiated` instead of `UserInitiated`.

## Questions

### What does exit code 137 mean when stopping an ECS task?

The container did not exit after SIGTERM within the stop timeout and was killed with SIGKILL, or it was killed earlier for running out of memory.

### Why did my ECS task come back after stop-task?

It belongs to a service, and the service keeps the desired number of tasks running. Change desired count with update-service to stop it for good.

### How long does ECS wait before killing a task?

The container's stopTimeout, 30 seconds by default, after which SIGKILL is sent.

## When this happens away from your desk

Stopping a misbehaving task is a quick fix that is easy to misjudge when the service will just start another. CloudConsole, a phone app for AWS, is built with guardrails and to show tasks, reasons and logs on a 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

- [AWS CLI Command Reference: ecs stop-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/stop-task.html)
- [StopTask API reference](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_StopTask.html)

## Related

- [ECS task stopped: Essential container exited with exit code 137](https://cloudconsole.dev/errors/ecs-exit-code-137)
- [ECS container exited with exit code 143 (SIGTERM)](https://cloudconsole.dev/errors/ecs-exit-code-143)
- [aws ecs describe-tasks](https://cloudconsole.dev/cli/ecs-describe-tasks)
- [aws ecs update-service](https://cloudconsole.dev/cli/ecs-update-service)
- [How to restart an ECS service](https://cloudconsole.dev/how-to/restart-ecs-service)
- [aws ecs describe-services](https://cloudconsole.dev/cli/ecs-describe-services)

---

Source: https://cloudconsole.dev/cli/ecs-stop-task

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