Updated Nov 20, 20265 min read

ECS CannotPullContainerError: Causes and Fixes

What Amazon ECS's CannotPullContainerError means on Fargate and EC2, how to read the message, and the fixes for missing routes to ECR, execution role permissions, wrong tags, architecture mismatches and Docker Hub rate limits.

Illustration for ECS CannotPullContainerError: Causes and Fixes

CannotPullContainerError means ECS started placing your task but could not download the container image, so the task stopped before any of your code ran. The text after the colon says why, and on Fargate it usually comes down to networking, permissions or the image reference.

This guide maps each message to its cause and the fix, starting with the ones that show up most.

How do you read the full error?

The ECS console shows the stopped reason on the task's page, and the CLI gives the full text, which matters since Fargate platform version 1.4 truncates long messages:

aws ecs describe-tasks --cluster prod --tasks arn:aws:ecs:eu-central-1:111122223333:task/prod/4f1c... \ --query 'tasks[0].{stopped:stoppedReason,containers:containers[].reason}'

The ECS troubleshooting page lists each message, and the table below groups them by cause.

Message containsCauseFix
request canceled while waiting for connectionNo route to ECRNAT gateway or ECR VPC endpoints
There is a connection issue between the task and Amazon ECRNo route to ECRSame
Check that the role has the permissionsExecution roleAdd ECR pull permissions
failed to resolve ref or not foundTag or digest does not existPush the image or fix the reference
toomanyrequestsDocker Hub rate limitAuthenticate or mirror to ECR
no space left on deviceEC2 instance disk fullClean images, larger volume

Does the task have a route to ECR?

A Fargate task in a private subnet reaches ECR through a NAT gateway or through VPC endpoints, and without either the pull times out. In a public subnet, the task needs assignPublicIp=ENABLED, since a public subnet without a public IP has no way out either. Per the ECR VPC endpoints docs, Fargate on platform version 1.4.0 or later needs all of these to pull without internet access:

  • com.amazonaws.<region>.ecr.dkr, for the registry API that pull uses
  • com.amazonaws.<region>.ecr.api, for authentication and image metadata
  • An S3 gateway endpoint, since ECR stores layers in S3
  • com.amazonaws.<region>.logs, when the task uses the awslogs log driver

The interface endpoints also need a security group that allows HTTPS from the task's subnets, and private DNS turned on.

Can the execution role pull the image?

On Fargate, the image is pulled with the task execution role, not the task role your code uses. It needs ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:GetDownloadUrlForLayer and ecr:BatchGetImage, which the managed AmazonECSTaskExecutionRolePolicy covers:

aws iam attach-role-policy \ --role-name ecsTaskExecutionRole \ --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

A repository in another account also needs a repository policy allowing that role, and an image in a private registry outside ECR needs repositoryCredentials pointing at a Secrets Manager secret the role can read.

Does the image tag exist, for this architecture?

failed to resolve ref usually means the tag in the task definition was never pushed, was deleted by a lifecycle policy, or points at another region's registry. Pin a specific tag or digest instead of :latest, since ECS resolves the tag to a digest at deploy and fails when that image is gone. An image built on an Apple Silicon Mac is arm64 only, and a task with the default x86_64 runtime platform cannot use it: build with docker buildx build --platform linux/amd64, or set runtimePlatform.cpuArchitecture to ARM64 in the task definition.

Is Docker Hub rate limiting you?

toomanyrequests: You have reached your pull rate limit comes from Docker Hub, which limits anonymous pulls per IP address, and every task behind one NAT gateway shares its address. A deploy that starts 20 tasks, each with a redis or nginx sidecar from Docker Hub, can hit it. Copy the image into ECR, use ECR's pull through cache rule for Docker Hub, or authenticate with repositoryCredentials. The Docker Hub usage docs list the current limits.

How does Encore handle images and pulls on AWS?

Encore

Encore is a backend framework with built-in infrastructure, and the pieces behind this error are set up as part of the environment. Per the AWS infrastructure docs, Encore provisions an ECR registry in your account, runs services on Fargate in private compute subnets with a NAT gateway for outbound traffic, and provisions an IAM role for the service that can pull from that registry. Environments live in your own AWS account, and Encore's CI builds each deploy's image and pushes it to that registry, so nobody types a tag into a task definition.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

The Docker Hub sidecar can go away too: a rate limiter that used a redis container next to the app becomes a cache cluster declared in Go, which Encore provisions as ElastiCache for Redis on AWS:

// ratelimit/ratelimit.go package ratelimit import ( "context" "time" "encore.dev/beta/errs" "encore.dev/storage/cache" ) // ElastiCache for Redis on AWS, an in-memory Redis under encore run. var cluster = cache.NewCluster("ratelimit", cache.ClusterConfig{ EvictionPolicy: cache.AllKeysLRU, }) // One counter per client per minute. var requests = cache.NewIntKeyspace[string](cluster, cache.KeyspaceConfig{ KeyPattern: "requests/:key", DefaultExpiry: cache.ExpireIn(time.Minute), }) type CheckParams struct { ClientID string } type CheckResponse struct { Remaining int64 } const limit = 120 //encore:api private method=POST path=/ratelimit/check func Check(ctx context.Context, p *CheckParams) (*CheckResponse, error) { n, err := requests.Increment(ctx, p.ClientID, 1) if err != nil { return nil, err } if n > limit { return nil, &errs.Error{Code: errs.ResourceExhausted, Message: "rate limit exceeded"} } return &CheckResponse{Remaining: limit - n}, nil }

Locally, encore run uses an in-memory Redis implementation for the same code. When a coding agent adds a resource like this, it writes the declaration with the code that uses it and tests it locally, and the deploy provisions it with the network path and permissions it needs, without anyone editing VPC endpoints or role policies.

Best fit: Teams on ECS who keep losing deploys to registry, network and role errors and want the image pipeline and its permissions handled for them.

What is the checklist?

  1. Read the full stoppedReason with aws ecs describe-tasks.
  2. Private subnet: NAT gateway, or ecr.dkr, ecr.api, S3 gateway and logs endpoints.
  3. Public subnet: assignPublicIp=ENABLED.
  4. Execution role has AmazonECSTaskExecutionRolePolicy or equivalent.
  5. The tag or digest exists in that region and matches the task's CPU architecture.
  6. Images from Docker Hub are mirrored to ECR or pulled with credentials.

Frequently asked questions

What causes CannotPullContainerError in ECS?

The task could not download its image, most often because of a task in a private subnet with no NAT gateway or ECR VPC endpoints, a task execution role without ECR permissions, an image tag that does not exist in the repository, or Docker Hub rate limits.

Which VPC endpoints does Fargate need to pull from ECR?

For platform version 1.4.0 and later: the com.amazonaws.region.ecr.dkr and com.amazonaws.region.ecr.api interface endpoints plus the S3 gateway endpoint, since image layers are stored in S3. With the awslogs driver, add the com.amazonaws.region.logs endpoint too.

Which role pulls the image on Fargate?

On Fargate, the task execution role pulls the image, not the task role, and it needs ecr:GetAuthorizationToken, ecr:BatchGetImage and ecr:GetDownloadUrlForLayer, which the AWS managed AmazonECSTaskExecutionRolePolicy includes.

How do I see the full CannotPullContainerError message?

Open the stopped task in the ECS console and read the stopped reason, or run aws ecs describe-tasks with the task ARN and look at stoppedReason and each container's reason. Fargate platform version 1.4 truncates long messages.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders