CannotPullContainerError ☁️ AWS

ECS task stopped: CannotPullContainerError: pull image manifest has been retried ... / ref pull has been retried

The ECS task couldn’t pull its image — no network route to the registry, missing ECR permissions, or a wrong image tag.

Seen on: AWS

Meaning

Fargate/EC2 tasks in private subnets need a NAT gateway or VPC endpoints (ecr.api, ecr.dkr, S3 gateway) to reach ECR. The task execution role needs ECR pull permissions, and the tag must exist.

Common causes

  • Private subnet without NAT or ECR/S3 VPC endpoints
  • assignPublicIp DISABLED in a public subnet
  • Task execution role lacks ecr:GetAuthorizationToken/BatchGetImage
  • Image tag doesn’t exist

⚡ Quick fix

  1. Add NAT or VPC endpoints, or enable public IP in public subnets
  2. Attach AmazonECSTaskExecutionRolePolicy
  3. Verify the image URI and tag

Detailed fix by platform

AWS CLI

  1. bash
    aws ecs describe-tasks --cluster app --tasks $TASK --query 'tasks[0].stoppedReason'
aws ecr describe-images --repository-name web --image-ids imageTag=1.4.2

How to diagnose

  1. Reason — stoppedReason text
  2. Network — Route to ECR?
  3. Role — Execution role policies
  4. Tag — Exists?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.