CannotPullContainerError AWS Origin: Platform & cloud Last updated 13 Oct 2026

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.

Exact message you may see pull image manifest has been retriedref pull has been retriedfailed to resolve ref
Explore the map of this error Full error map →
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:

Where this error sits

Origin: Platform & cloud. Errors that are often confused with or caused by this one (click to open):

ACR unauthorized — Azure Container Registry: unauthorized: authentication required, visit https://aka.ms/acr/authorization (AKS ErrImagePull 401) (Azure)ACR unauthorizedactively refused it — HttpRequestException: No connection could be made because the target machine actively refused it (localhost:5001) (.NET)actively refused itContainer failed to start — Cloud Run: The user-provided container failed to start and listen on the port defined provided by the PORT=8080 environment variable (Google Cloud / Firebase)Container failed to s…default backend - 404 — Ingress returns "404 Not Found" / "default backend - 404" (ingress-nginx) (Kubernetes)default backend - 404ECR token expired — denied: Your authorization token has expired. Reauthenticate and try again. (Amazon ECR) (AWS)ECR token expiredEROFS — npm ERR! code EROFS — EROFS: read-only file system (npm)EROFSEssential container in task exited — ECS: Essential container in task exited (task keeps stopping) (AWS)Essential container i…Exited (0) — Docker container exits immediately (Exited (0) / Exited (1) right after start) (Docker)Exited (0)CannotPul…

Explore the map of this error Full error map →

🧠 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.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.