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

Short description

To 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 pane, 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: A stopped task is visible only for 60 minutes after it stops.

1. Open the Amazon ECS console.
2. In the navigation pane, choose Clusters, and then select the cluster that contains your stopped task.
3. On your cluster 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. Review the stopped reason codes and stop time at the top of the task page.
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 associated with the task 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)

This stopped reason appears when Amazon ECS stops tasks because the service scales down or performs a rolling deployment. To suspend and resume scaling 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

This stopped reason appears when you stop or terminate an Amazon Elastic Compute Cloud (Amazon EC2) container instance that has running tasks. To investigate why Amazon EC2 terminated your instance, see Why did Amazon EC2 unexpectedly terminate my instance?

Container instance deregistration forced by user

This stopped reason appears when you force the deregistration of a container instance that has running tasks.

Essential container in task exited

This stopped reason appears when a container marked as essential in the task definition exits or dies. When an essential container exits, Amazon ECS stops the task.

Task failed to start

If you see the "Task failed to start" error, first expand the container. Then, inspect the Status reason row to identify the cause of the task state 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 messages.
• If you used the Amazon 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 Amazon ECS API failure reasons.

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 "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 error "the closest matching container-instance container-instance-id encountered error 'AGENT'" for my service in Amazon ECS?

How do I resolve Amazon ECS tasks that fail to pull images from Amazon ECR?

How do I resolve "CannotPullContainerError" errors when I launch an EC2 task in Amazon ECS?