CloudConsole

CannotPullContainerError: pull image manifest has been retried

Updated 17 November 2026 · How we write and check guides

Short answer

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.

Fix networking for private subnets, in 3 steps: 1. com.amazonaws.eu-west-2.ecr.api and com.amazonaws.eu-west-2.ecr.dkr…; 2.…
The diagnosis and fix steps from this page, in the order to try them; commands and details are below.

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

EndingCauseFix
i/o timeout, context deadline exceededNo route to ECR: private subnet without NAT, or a Fargate task in a public subnet with assignPublicIp disabledAdd a NAT gateway, enable a public IP, or add VPC endpoints
not found, manifest unknownTag never pushed, deleted by a lifecycle policy, or a typo in repository or regionPush the image or fix the reference
403 Forbidden, deniedExecution role lacks ECR permissions, or a cross-account repository policy doesn't allow this accountGrant the permissions below; update the repository policy
toomanyrequestsDocker Hub anonymous pull rate limitMirror the image into ECR (a pull-through cache rule works well)
no match for platform in manifestImage built for arm64 only and the task runs on x86_64, or the reverseBuild 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.api and com.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 S3
  • com.amazonaws.eu-west-2.logs if the task uses the awslogs driver

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.dkr endpoint. Without ecr.api and 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.

CloudConsole ECS service screen on a phone, for following up on CannotPullContainerError away from your desk
When this happens away from your desk

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

Sources