Why do the tasks in my Amazon ECS cluster fail to start?

Short description

To successfully place your task in your cluster, choose one of the following solutions:

• If you place your task with the Amazon ECS service, then complete the steps in the Check your service event messages and the Check the stopped task for errors sections.
• If you run your task as a standalone task or scheduled task, then complete the steps in the Check the stopped task for errors section.

Resolution

Check your service event messages

To check your service event messages, complete the following steps:

1. Open the Amazon ECS console.
2. In the navigation menu, choose Clusters, and then select the cluster that contains your service.
3. On the Services tab of your cluster's page, in the Service Name column, select the service that you want to inspect.
4. On your service's page, choose Events.
5. In the Message column, look for errors or other useful information.

Based on your findings from step 5, review service event messages to troubleshoot your error.

Note: Service events show only the most recent 100 events.

Check the stopped task for errors

To check the stopped task for errors, complete the following steps:

Important: You can see a stopped task only if it was stopped within the last 60 minutes.

1. Open the Amazon ECS console.
2. In the navigation menu, choose Clusters, and then select the cluster that contains your stopped task.
3. On your cluster's page, choose the Tasks tab.
4. In the Filter desired status dropdown list, choose Stopped, and then select the stopped task that you want to inspect. The most recent stopped tasks appear first.
5. Stopped reason codes, along with the stop time, appear on the top of the page of your stopped tasks.
6. Based on your findings from step 5, review the following stopped reason codes to resolve your error:

Task failed ELB health checks in (elb elb-name)

The current task failed the Elastic Load Balancing health check for the load balancer that's associated with the task's service. For more information, see Troubleshooting service load balancers in Amazon ECS.

Note: This root cause is applicable only for tasks that were launched as part of the service.

Scaling activity initiated by (deployment deployment-id)

You see this Stopped reason if tasks are stopped because services are downscaled or under rolling deployment. For more information on how to suspend and resume scaling to avoid potential issue during deployment, see Troubleshooting service auto scaling in Amazon ECS.

Note: This root cause is applicable only for tasks that were launched as part of the service.

Host EC2 (instance id) stopped/terminated

You see this Stopped reason if you stop or terminate an Amazon Elastic Compute Cloud (Amazon EC2) container instance that has running tasks. To investigate why your Amazon EC2 instance was terminated, see Why did Amazon EC2 terminate my instance?

Container instance deregistration forced by user

If you force the deregistration of a container instance with running tasks, then you see this Stopped reason.

Essential container in task exited

If a container marked as essential in the task definition exits or dies, the task might be stopped. You see this Stopped reason if an essential container exists and causes the task to stop.

Task failed to start

If you see the "Task failed to start" error, first expand the container. Then, Inspect the Status reason row to see what caused the task state to change:

• If the container status has the error CannotPullContainerError, then see CannotPullContainer task errors in Amazon ECS.
• For information on other error messages, see Amazon ECS stopped tasks error codes for the Amazon EC2 launch type.
• If you used the EC2 launch type and need more information, first connect to the container instance with SSH, Session Manager, or Instance Connect. Then, inspect the Docker container locally. For more information, see Inspect Docker containers in Amazon ECS.

Also, review API failure reasons in Amazon ECS.

If you use any task placement constraints or strategies, your cluster must use instances that meet the requirements of your constraints or strategies.

Related information

How do I resolve the "[AWS service] was unable to place a task because no container instance met all of its requirements" error in Amazon ECS?

How do I resolve "the closest matching container-instance container-instance-id has insufficient CPU units available" error in Amazon ECS?

How do I resolve "the closest matching container-instance container-instance-id encountered error 'AGENT'" error for my service in Amazon ECS?

How can I resolve the Amazon ECR error "CannotPullContainerError: API error" in Amazon ECS?

How can I resolve the "CannotPullContainerError" error in my Amazon ECS EC2 Launch Type Task?