aws ecs describe-tasks: Check ECS Task Status in CI
aws ecs describe-tasks returns the lifecycle status, container exit codes, and stop reason for ECS tasks, letting CI tell a successful migration from a crashed one.
After run-task, you must verify the task actually succeeded. describe-tasks exposes the container exitCode and stoppedReason, which is the only reliable success signal.
What it does
aws ecs describe-tasks returns details for the task ARNs in --tasks on --cluster: lastStatus, the containers array (with exitCode), and stoppedReason. A task can reach STOPPED with a container exitCode of 1, so you must inspect the exit code, not just the status.
Common usage
aws ecs wait tasks-stopped --cluster prod --tasks "$TASK_ARN"
aws ecs describe-tasks --cluster prod --tasks "$TASK_ARN" \
--query 'tasks[0].{status:lastStatus,reason:stoppedReason,exit:containers[0].exitCode}'Options
| Flag | What it does |
|---|---|
| --cluster <name> | Cluster the tasks run on |
| --tasks <arn|id...> | Task ARNs or IDs to describe (required) |
| --query tasks[0].containers[0].exitCode | Extract the container exit code |
| --include TAGS | Also return resource tags |
In CI
Gate the job on containers[0].exitCode == 0, not on lastStatus being STOPPED, because a failed task is also STOPPED. Run aws ecs wait tasks-stopped first so the task has finished before you read the exit code. stoppedReason explains task-level failures (out of memory, image pull) while exitCode explains application failures.
Common errors in CI
A null exitCode with a stoppedReason like "Essential container in task exited" or "CannotPullContainerError" means the container never ran the command (infra problem), versus an exitCode of 1 which means your code failed. "ClusterNotFoundException" means a wrong --cluster. "InvalidParameterException: Tasks cannot be empty" means an empty --tasks variable. "AccessDeniedException" means missing `ecs:DescribeTasks".