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

Last updated: 2022-12-22

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.

Resolution

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:

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 https://registry-1.docker.io/v2/manifests/sha256:2bb501e6429 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.dkr.ecr.ap-southeast-2.amazonaws.com/image-name:tag: 123456789.dkr.ecr.ap-southeast-2.amazonaws.com/image-name:tag: 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 docker.io/library/invalid-name:non-existenttag: pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed

To resolve this issue, verify 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.


Did this article help?


Do you need billing or technical support?