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

5 minute read

When I launch an EC2 task in Amazon Elastic Container Service (Amazon ECS), I receive the following error: "CannotPullContainerError".

Short description

The CannotPullContainerError occurs due to any of the following issues:

  • An Amazon Elastic Compute Cloud (Amazon EC2) Launch Type task can't pull the image due to an incorrectly configured network.
  • An AWS Identity and Access Management (IAM) role doesn't have the right permissions to pull the image.
  • There's a DockerHub rate limit.
  • The image name or tag doesn't exist.

To troubleshoot the errors for Amazon ECS tasks that fail to start, use the AWSSupport-TroubleshootECSTaskFailedToStart runbook. Then, refer to the relevant troubleshooting steps for your issue.



  • Use the AWSSupport-TroubleshootECSTaskFailedToStart runbook in the same AWS Region where your ECS cluster resources are located.
  • When using the runbook, you must use the most recently failed Task ID. If the failed task is part of an Amazon ECS service, then use the most recently failed task in the service. The failed task must be visible in ECS:DescribeTasks during the automation. By default, stopped ECS tasks are visible for 1 hour after entering the Stopped state. Using the most recently failed task ID prevents the task state cleanup from interrupting the analysis during the automation.

For instructions on how to initiate the runbook, see AWSSupport-TroubleshootECSTaskFailedToStart. Based on the output of the automation, use one of the following manual troubleshooting steps.

Your Amazon ECS container instance network configuration is incorrect

If your Amazon ECS container instance doesn't have an internet connection, then it can't reach the Amazon Elastic Container Registry (Amazon ECR) endpoint. Without a connection to the endpoint, the instance can't pull the image. To verify that your ECS container instance has internet access, review the following points:

Your IAM role doesn't have the right permissions to pull images

Confirm that the instance IAM role associated with the instance profile has permissions to access the Amazon ECR repository.

Note: The AWS managed policy AmazonEC2ContainerRegistryReadOnly provides the minimum permissions required to pull images.

The DockerHub pull rate limit is reached

If you're trying to pull an image from DockerHub and you reached your pull rate limit, then you receive the following error message:

"CannotPullContainerError: inspect image has been retried 5 time(s): httpReaderSeeker: failed open: unexpected status code Too Many Requests - Server message: toomanyrequests:"

To resolve this issue, review the steps in How do I resolve the error "CannotPullContainerError: You have reached your pull rate limit" in Amazon ECS?

The image name or tag doesn't exist

If an image or its associated tag hosted in Amazon ECR defined in your task definition doesn't exist, then you receive the following error:

"Cannotpullcontainererror: pull image manifest has been retried 1 time(s): failed to resolve ref 123456789** not found**"

To resolve this issue, verify the image field in your task definition. Confirm that the corresponding repository and defined tag is present in the container registry that you're pulling from.

If your task pulls an image from a registry other than Amazon ECR and is missing information, then you receive a different error. The following error occurs if the image doesn't exist, the tag doesn't exist, or the registry credentials aren't provided:

"Cannotpullcontainererror: pull image manifest has been retried 1 time(s): failed to resolve ref pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed"

To resolve this issue, check the image field in your task definition. Confirm that the image exists in the corresponding container registry. If the image exists, then make sure that you provide the correct credentials. For more information, see Private registry authentication for tasks.