AWS Builder Center
🔍 How to Investigate a Stopped ECS Task

🔍 How to Investigate a Stopped ECS Task

A practical guide to finding the root cause of a stopped Amazon ECS task by checking stop reasons, exit codes, service events, and container logs.

Series: ECS Made Practical (3 articles)

  1. 1
    🔍 How to Investigate a Stopped ECS Task This article
DevOps Enginer
If you have worked with Amazon ECS, you have probably seen this situation: you deploy an application, wait for the task to start, and suddenly its status changes to Stopped.
The first reaction is usually to restart the task and try again. However, restarting does not always solve the real problem. Before taking action, it is important to understand why the task stopped.
In this article, I will share a simple checklist for investigating a stopped task in Amazon ECS.

🛑 1. Check the Stop Reason

The first step is to locate the stopped task.
In the AWS Console, go to:
ECS → Clusters → your cluster → Tasks → Stopped
Open the task and check:
  • 🔎 Stop code
  • 📝 Stopped reason
  • 📦 Container reason
  • ⚠️ Exit code
These details can indicate whether the problem is related to the application, container image, permissions, memory, or network configuration.
You can also use the AWS CLI:
aws ecs list-tasks \
--cluster <cluster-name> \
--desired-status STOPPED \
--region <region>
This command returns the ARN of the stopped task. Use that ARN to retrieve more details:
aws ecs describe-tasks \
--cluster <cluster-name> \
--tasks <task-arn> \
--region <region> \
--query 'tasks[0].{StopCode:stopCode,StoppedReason:stoppedReason,Containers:containers[].{Name:name,ExitCode:exitCode,Reason:reason}}' \
--output json

🚨 2. Understand Common Errors

Some common examples include:
  •  TaskFailedToStart : the task could not start because of an image, network, or permission issue;
  •  EssentialContainerExited : the main container process stopped;
  •  exitCode 137 : the container may have exceeded its memory limit;
  • Health check failure: the application did not respond as expected;
  •  CannotPullContainerError : ECS could not download the image from Amazon ECR.
These messages do not replace a complete investigation, but they help point you in the right direction.

📊 3. Check the Logs

After identifying the error, check the container logs in Amazon CloudWatch.
Look for:
  • application startup errors;
  • missing environment variables;
  • connection failures;
  • permission errors;
  • repeated crashes;
  • health check failures.
Logs often reveal details that are not visible in the ECS task summary.

✅ Conclusion

Investigating a stopped ECS task starts with a simple habit: read the error details before restarting it. By checking the  stopCode ,  stoppedReason ,  exitCode , and container logs, it becomes much easier to determine whether the problem is in the application or the infrastructure.
Have you ever had an ECS task stop unexpectedly? What was the cause, and how did you solve it? Share your experience in the comments — it may help another builder troubleshoot their next deployment.

Series: ECS Made Practical (3 articles)

  1. 1
    🔍 How to Investigate a Stopped ECS Task This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article