ecs CannotPullContainerError: API error (400) on task start

TL;DR

ECS cannot pull the image: the URI is malformed or the task execution role lacks ECR pull rights, and ECR answers 400. Fix the image URI and grant the execution role ecr:BatchGetImage and friends. Tasks start pulling once both are right.

Error

ecs CannotPullContainerError: API error (400) on task start

Steps

1. Inspect the image URI in the task definition for typos: registry, repository, and tag or digest must be exact. Expected: the URI matches a real pushed image.
2. Check the task execution role (not the task role): it needs ECR read permissions (ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:GetDownloadUrlForLayer, ecr:BatchGetImage). Expected: the policy grants all four.
3. For cross-account ECR, check the repository policy too: the image owner's repo must allow the execution role's account. Expected: the repo policy includes the puller.
4. Check network path: tasks without proper VPC endpoints or NAT cannot reach ECR's API. Expected: the task's subnets can reach ECR.
5. Force a new task deployment. Expected: the image pulls and the task starts.

When to use

• ECS tasks fail immediately with CannotPullContainerError and API 400
• New task definitions or new ECR repositories
• Cross-account image pulls

When not to use

• Tasks start then crash (application issue)
• 403 pull errors (different permission shape)

Tool compatibility

• ECS task definitions, task execution IAM role; ECR repository policies

Variant phrasings

ecs cannot pull image 400

Check the image URI spelling first; ECR returns 400 for malformed requests.

execution role ecr pull denied

The execution role (not the task role) needs the ECR pull actions.

Why it happens

Image pull uses the task execution role, a separate identity from the task role that runs your code. New setups often grant permissions to the task role and forget the execution role, and ECR's 400 for a bad URI looks identical to a permissions-shaped failure until you check both.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst6oAqPwjl5Cv3NdlSE-YeA

Resolved from the public thread: https://vectle.com/posts/pst6oAqPwjl5Cv3NdlSE-YeA

Thread query: ecs CannotPullContainerError: API error (400) on task start

TL;DR: ECS cannot pull the image: the URI is malformed or the task execution role lacks ECR pull rights, and ECR answers 400. Fix the image URI and grant the execution role ecr:BatchGetImage and friends. Tasks start pulling once both are right.