AWS ECS Support
ECS CannotPullContainerError: why images fail to pull and the fix.
CannotPullContainerError means the ECS agent could not download your image. The message usually contains the real reason, such as a timeout, an authorization failure, a missing tag or a rate limit. We map the message to the cause and fix the network path or permission behind it.
When You Need This
The situations where this work pays for itself.
Signs it is time
- Tasks stay in PROVISIONING or PENDING then stop with CannotPullContainerError
- It started after moving tasks to private subnets
- The error says i/o timeout or context deadline exceeded
- The error says pull access denied or manifest unknown
- Docker Hub images fail intermittently with rate limit messages
What you get
- Exact cause of the pull failure
- Corrected IAM, endpoints or security group rules in code
- Pull through cache or mirroring for external images
- Alerting on task start failures
How we do it
A clear, safe process you can follow along with.
1. Read the full error text
In the stopped task details the message names the failure. i/o timeout points to networking. no basic auth credentials or pull access denied point to permissions or repository. manifest not found means the tag or digest is wrong. toomanyrequests means a registry rate limit.
2. Verify the image reference
We check the account ID, Region, repository name and tag in the task definition against ECR. A tag that was never pushed, or a CI job that pushes after the deploy starts, is a very common cause.
3. Check the task execution role
The task execution role needs ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:GetDownloadUrlForLayer and ecr:BatchGetImage, which AmazonECSTaskExecutionRolePolicy provides. Cross-account repositories also need a repository policy. Note that the task role is not used for pulls.
4. Check the network path to ECR
Tasks in private subnets need either a NAT gateway or VPC endpoints. For ECR that means interface endpoints for com.amazonaws.region.ecr.api and ecr.dkr, plus the S3 gateway endpoint because image layers come from S3, and a logs endpoint if you use awslogs. The endpoint security group must allow 443 from the task.
5. Check security groups, NACLs and endpoint policies
The task security group must allow outbound 443. Restrictive VPC endpoint policies or S3 gateway policies that block the ECR layer bucket cause pulls to fail while auth works.
6. Handle third-party registries
For Docker Hub, we use pull through cache in ECR or mirror base images into your own repositories, or pass registry credentials from Secrets Manager with repositoryCredentials, to avoid anonymous rate limits.
7. Verify
We launch a test task, confirm it reaches RUNNING, and add an EventBridge rule on task state changes that alerts on pull failures.
Mistakes we help you avoid
Common ways this goes wrong, and what we do instead.
Adding permissions to the task role
Image pulls use the execution role. The task role only applies to your running code.
Forgetting the S3 endpoint
ECR auth and manifest calls work while layer downloads time out.
Using the latest tag in deployments
The tag may point to an image that does not exist yet or changes between tasks.
Opening a NAT gateway for everything
It works but adds data processing cost. Endpoints are often cheaper for ECR traffic.
Frequently Asked Questions
Why does ECS fail to pull from ECR in a private subnet?
There is no route to ECR. Add a NAT gateway or create the ECR api, ECR dkr and S3 gateway VPC endpoints and allow port 443 from the tasks.
Which IAM role does ECS use to pull images?
The task execution role. It needs the ECR pull permissions, which the managed AmazonECSTaskExecutionRolePolicy includes.
What does toomanyrequests mean in ECS?
The registry, commonly Docker Hub for anonymous pulls, is rate limiting you. Use ECR pull through cache, mirrored images or authenticated pulls.
Want Help With ECS CannotPullContainerError: why images fail to pull and the fix?
Schedule an appointment. Tell us about your environment and we will outline the safest, highest-value approach.
Schedule Appointment › No commitment required