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

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:

• Confirm that your instances have access to the internet through either an internet gateway or Network Address Translation (NAT) gateway.
  Note: Instead of a NAT gateway, you can use AWS PrivateLink. To avoid errors, make sure that AWS PrivateLink is correctly configured.
• Verify that inbound HTTPS access is allowed through port 443 at the instance, security group, and network access control list (network ACL) levels.
  To troubleshoot NAT gateway connectivity issues, see Why can't my EC2 instances access the internet using a NAT gateway?
  To troubleshoot internet gateway connectivity issues, see Why can't my EC2 instance connect to the internet using an internet gateway?
• If you're using a VPC endpoint to connect to an Amazon ECR endpoint, then check your security groups. Confirm that the security groups for your VPC endpoint allow the ECS container instance to use them.
• If you receive the error message "CannotPullContainerError: API error", then see How can I resolve the Amazon ECR error "CannotPullContainerError: API error" in Amazon ECS?

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 resolvethis 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.