AWS ECS: CannotPullContainerError, pull image manifest has been retried

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# The precise reason is recorded on the stopped task
aws ecs describe-tasks --cluster prod --tasks <id> \
  --query 'tasks[0].{reason:stoppedReason,containers:containers[].reason}'

# Private subnets need endpoints, or a NAT gateway
aws ec2 describe-vpc-endpoints --filters Name=vpc-id,Values=vpc-123 \
  --query 'VpcEndpoints[].ServiceName'
# ecr.api, ecr.dkr, logs, and an S3 gateway endpoint for the layers

# Fargate in a public subnet must be told to take a public IP
"networkConfiguration": {"awsvpcConfiguration": {"assignPublicIp": "ENABLED"}}

# Only then check the execution role
aws iam simulate-principal-policy --policy-source-arn <execRoleArn> \
  --action-names ecr:GetAuthorizationToken ecr:BatchGetImage

How to diagnose Cloud errors

Cloud provider errors are overwhelmingly one of two things: IAM (the caller is not permitted, or the credentials are not the ones you think) or quota (the account limit was reached). Providers deliberately return the same vague AccessDenied for a missing permission, a deny in a boundary or SCP, and a resource policy that excludes you, so the fix begins with identifying which identity made the call.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Confirm the identity first: aws sts get-caller-identity, az account show, or gcloud auth list. An unexpectedly large share of AccessDenied errors are the right policy on the wrong principal.
2. Use the provider's policy simulator (IAM Policy Simulator, gcloud policy-troubleshoot) rather than reading policy JSON. It accounts for boundaries, SCPs and resource policies that are invisible in a single document.
3. Check CloudTrail / Activity Log / Cloud Audit Logs for the denied call. The log entry names the exact action and resource ARN, which the client-side error usually omits.
4. For quota errors, look up the current limit and the current usage before requesting an increase: many quotas are per-region and per-account, and the resource you think is idle may be counted.
5. Verify the region. A resource that "does not exist" very often exists in a different region than the one your CLI profile defaults to.

Tools worth reaching for

• aws sts get-caller-identity
• IAM Policy Simulator
• gcloud policy-troubleshoot
• CloudTrail / Activity Log

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 docs.aws.amazon.com

Related Cloud errors

• AWS CloudFormation: Stack is in ROLLBACK_COMPLETE state and can not be updatedThe stack's first create failed and rolled back. A stack in that state has no resources and…
• AWS EC2: Instance limit exceededAccount has reached the limit for number of instances of a specific type in a region.
• AWS IAM: Policy syntax errorIAM policy JSON is malformed or contains invalid actions, resources, or conditions.
• AWS Lambda: Function timeoutLambda function exceeded maximum execution time. Default is 3 seconds, max is 15 minutes.
• AWS RDS: Connection timeoutCannot connect to RDS instance. Security group blocking, wrong endpoint, or instance not…
• AWS S3: Access DeniedIAM permissions insufficient to access S3 bucket. Bucket policy, ACL, or IAM policy blocking…
• AWS S3: PermanentRedirect, wrong regional endpointThe request went to the wrong regional endpoint. S3 bucket names are global but buckets live…
• AWS: AccessDenied when calling the AssumeRole operationRole assumption requires permission on both sides: the caller needs sts:AssumeRole in its…

See all 25 Cloud errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.
• Frontend 23Hydration mismatches, bundler resolution, layout shift and font loading.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.