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.

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.
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.
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 usescom.amazonaws.<region>.ecr.api, for authentication and image metadatacom.amazonaws.<region>.logs, when the task uses the awslogs log driverThe interface endpoints also need a security group that allows HTTPS from the task's subnets, and private DNS turned on.
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.
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.
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.
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.

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.
stoppedReason with aws ecs describe-tasks.ecr.dkr, ecr.api, S3 gateway and logs endpoints.assignPublicIp=ENABLED.AmazonECSTaskExecutionRolePolicy or equivalent.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.
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.
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.
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.