CloudConsole

aws ecs stop-task

Updated 16 November 2026 · How we write and check guides

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.

Terminal running aws ecs stop-task --cluster prod --task…
A worked example from this page. Copy commands from the text below, not from the image.

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 codeWhat happened
0The process caught SIGTERM and exited cleanly.
143The process was terminated by SIGTERM without handling it (128 + 15). Usually harmless.
137The 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 app → · Download on the App Store

Sources