CannotPullContainerError: pull image manifest has been retried
The ECS agent or Fargate couldn't download the container image, so the task stopped before your container ever ran. The ending of the message gives the reason: "i/o timeout" means no network path to the registry (often a private subnet with no NAT gateway or ECR VPC endpoints), "not found" means the tag or digest doesn't exist, and "403" or "denied" points at the task execution role or the repository policy.
Read the full message
The text comes from the stopped task's stoppedReason:
CannotPullContainerError: pull image manifest has been retried 7 time(s): failed to resolve ref
123456789012.dkr.ecr.eu-west-2.amazonaws.com/api:v42: …: dial tcp 3.10.x.x:443: i/o timeout
CannotPullContainerError: pull image manifest has been retried 7 time(s): failed to resolve ref
123456789012.dkr.ecr.eu-west-2.amazonaws.com/api:v42: …: not found aws ecs describe-tasks --cluster prod --tasks <task-arn> \
--query 'tasks[0].[stoppedReason,containers[0].image]' --output text The retry count varies; what matters is the reason at the end.
Causes by message
| Ending | Cause | Fix |
|---|---|---|
i/o timeout, context deadline exceeded | No route to ECR: private subnet without NAT, or a Fargate task in a public subnet with assignPublicIp disabled | Add a NAT gateway, enable a public IP, or add VPC endpoints |
not found, manifest unknown | Tag never pushed, deleted by a lifecycle policy, or a typo in repository or region | Push the image or fix the reference |
403 Forbidden, denied | Execution role lacks ECR permissions, or a cross-account repository policy doesn't allow this account | Grant the permissions below; update the repository policy |
toomanyrequests | Docker Hub anonymous pull rate limit | Mirror the image into ECR (a pull-through cache rule works well) |
no match for platform in manifest | Image built for arm64 only and the task runs on x86_64, or the reverse | Build for the task's architecture or set runtimePlatform |
Fix networking for private subnets
Tasks without internet access need these VPC endpoints to pull from ECR:
com.amazonaws.eu-west-2.ecr.apiandcom.amazonaws.eu-west-2.ecr.dkr(interface endpoints, with private DNS enabled)com.amazonaws.eu-west-2.s3(gateway endpoint on the subnets' route tables), because image layers are served from S3com.amazonaws.eu-west-2.logsif the task uses theawslogsdriver
The interface endpoints' security group must allow HTTPS (443) from the tasks' security group. Check what a service is using:
aws ecs describe-services --cluster prod --services api \
--query 'services[0].networkConfiguration.awsvpcConfiguration'Fix permissions and the image reference
The task execution role (not the task role) pulls the image. The AWS managed policy AmazonECSTaskExecutionRolePolicy covers ECR; a custom policy needs:
"Action": ["ecr:GetAuthorizationToken", "ecr:BatchCheckLayerAvailability",
"ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage"] Confirm the tag exists in the region the task runs in:
aws ecr describe-images --repository-name api --image-ids imageTag=v42 \
--query 'imageDetails[0].[imagePushedAt,imageDigest]' If it was deleted by a lifecycle rule, push it again or deploy a tag that exists. Pinning task definitions to an image digest avoids surprises when tags move.
Mistakes to avoid
- Adding ECR permissions to the task role. The pull happens before your container exists, using the execution role.
- Creating only the
ecr.dkrendpoint. Withoutecr.apiand the S3 gateway endpoint, pulls still time out. - Letting a lifecycle policy expire images that running services still reference. The next scale-out or task replacement fails with "not found".
Questions
Why does ECS Fargate fail to pull an image from ECR in a private subnet?
The task has no network path to ECR. Add a NAT gateway or create the ecr.api and ecr.dkr interface endpoints plus an S3 gateway endpoint.
Which role does ECS use to pull container images?
The task execution role. It needs ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:GetDownloadUrlForLayer and ecr:BatchGetImage.
What does CannotPullContainerError not found mean?
The image tag or digest doesn't exist in that repository and region. It may never have been pushed, or a lifecycle policy removed it.

Image pull failures stop new tasks from starting, which hurts most during a scale-out or after a deploy. CloudConsole, a phone app for AWS, is built to show service events and running task counts on your phone, so you can see when capacity isn't arriving.
Did it start after a deploy? What changed? on the app’s alarm screen lists the deploys and configuration changes from the hour before the alarm fired.
About the app → · Download on the App Store