CloudConsole

aws ecs describe-tasks

Updated 16 November 2026 · How we write and check guides

Short answer

aws ecs describe-tasks --cluster my-cluster --tasks <task-id> returns a task's status, stoppedReason, stopCode, each container's exit code and reason, health status and network attachments. It is the command that tells you why a task stopped, and it works for stopped tasks for a limited time after they stop.

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

What the command does

Up to 100 task IDs or ARNs can be described per call. Each entry in tasks[] includes lastStatus and desiredStatus, taskDefinitionArn, group (for example service:orders-api), startedAt, stoppedAt, stopCode, stoppedReason, healthStatus, attachments (the ENI for awsvpc tasks) and containers[], each with lastStatus, exitCode, reason, healthStatus and the image digest that actually ran.

Syntax

aws ecs describe-tasks --cluster my-cluster --tasks <task-id-or-arn> [...] [--include TAGS]

Worked examples

Why did it stop?

aws ecs describe-tasks --cluster prod --tasks 0123456789abcdef0123456789abcdef \
  --query "tasks[0].{stopCode:stopCode,reason:stoppedReason,containers:containers[].[name,exitCode,reason]}" \
  --output json

Recently stopped tasks of a service, with reasons:

TASKS=$(aws ecs list-tasks --cluster prod --service-name orders-api \
  --desired-status STOPPED --query "taskArns[]" --output text)
aws ecs describe-tasks --cluster prod --tasks $TASKS \
  --query "tasks[].[stoppedAt,stopCode,stoppedReason,containers[0].exitCode]" --output text

Private IP of a Fargate task:

aws ecs describe-tasks --cluster prod --tasks 0123456789abcdef0123456789abcdef \
  --query "tasks[0].attachments[0].details[?name=='privateIPv4Address'].value | [0]" --output text

Which image digest is actually running:

aws ecs describe-tasks --cluster prod --tasks 0123456789abcdef0123456789abcdef \
  --query "tasks[0].containers[].[name,image,imageDigest]" --output table

Is ECS Exec ready on this task?

aws ecs describe-tasks --cluster prod --tasks 0123456789abcdef0123456789abcdef \
  --query "tasks[0].[enableExecuteCommand,containers[0].managedAgents[0].lastStatus]" --output text

Decoding stop reasons

You seeMeaning
Exit code 137Killed with SIGKILL: out of memory, or did not exit within the stop timeout. See exit code 137.
Exit code 139Segmentation fault in the process.
Exit code 143Stopped by SIGTERM, typically a normal stop or scale-in.
Essential container in task exitedThe main container stopped; check its exit code and logs.
Task failed ELB health checksThe load balancer marked it unhealthy and ECS replaced it.
CannotPullContainerError / ResourceInitializationErrorImage pull or secrets retrieval failed, often networking or execution-role permissions.
stopCode SpotInterruptionFargate Spot capacity was reclaimed.

Gotchas

  • Stopped tasks disappear. ECS keeps stopped tasks visible for only about an hour. For longer history, capture task state change events with EventBridge.
  • Short IDs need the right cluster. A task ID without the matching --cluster returns a MISSING failure, not an error.
  • Exit code missing? If the container never started (pull or secrets failure), there is no exit code; the reason is in stoppedReason or containers[].reason.
  • Logs hold the detail. Exit codes tell you how a process died, not why; read the container's log stream next.
  • Health status needs a health check. healthStatus only reflects container health checks defined in the task definition. With none defined it stays UNKNOWN, which is normal and not a fault.

Questions

How do I find why an ECS task stopped?

Run describe-tasks on the task and read stopCode, stoppedReason and containers[].exitCode and reason. List recent stopped tasks with list-tasks --desired-status STOPPED.

What does ECS exit code 137 mean?

The container was killed with SIGKILL, usually for exceeding its memory limit or not shutting down within the stop timeout after SIGTERM.

What does "task stopped by user" mean?

stopCode UserInitiated: someone or something called StopTask, such as a deployment script, a person in the console, or automation.

When this happens away from your desk

A stopped task leaves its reason behind for only a short time, which matters when you are paged. CloudConsole, a phone app for AWS, is built to show stopped tasks, their reasons and their logs on a phone.

About the app → · Download on the App Store

Sources