How can I resolve the “CannotPullContainerError” error in my Amazon ECS EC2 Launch Type Task?
Last updated: 2022-06-23
When I launch an EC2 task in Amazon Elastic Container Service (Amazon ECS), I'm receiving the following error: "CannotPullContainerError". How can I resolve this issue?
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
- A DockerHub rate limit
Your Amazon ECS Container instance network configuration is incorrect
If your Amazon ECS Container instance used for ECS Workload doesn't have an Internet connection, it can't reach the Container Registry endpoint to 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) level.
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 are using a VPC Endpoint to connect to an Amazon Elastic Container Registry (Amazon ECR) Endpoint, then confirm that the security groups for your VPC endpoint allow the ECS Container Instance to use them.
- If your error message is the following CannotPullContainerError: API error, then complete the steps at 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 has been reached
If you are trying to pull an image from DockerHub and have reached your pull rate limit, 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?