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:
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;
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.
Loading article