ecs CannotPullContainerError: API error (400) on task start

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

The task stopped because a container marked essential exited, and ECS stops the whole task when that happens. Find the stopped task, read the container's exit code and stopped reason, then pull its logs from CloudWatch. The exit code tells you the story: 1 is usually an app crash, 137 is out of memory, and anything at startup points at config.

ECS "Essential container in task exited": task stopped debugging

Steps

1. Find the stopped task in the ECS console or via the API and read its stopped reason and the stopped container's exit code.

Expected: You have the exit code and the stopped reason string.

2. Open the container's CloudWatch logs around the stop time and look for the last error or traceback.

Expected: You can see what the container was doing when it exited.

3. Map the exit code: 1 is an app-level crash, 137 is OOM kill, 0 on an essential container usually means a misconfigured essential flag or a one-shot container.

Expected: You have a leading hypothesis tied to the exit code.

4. Fix the cause (app bug, memory limit, bad env config), push a new task definition revision, and redeploy.

Expected: New tasks start and stay running.

Use this when

• The ECS stopped reason says essential container in task exited.
• Tasks start and then stop within seconds or minutes.
• A new task definition revision just deployed and tasks keep dying.

Not for this skill when

• Tasks that never start: image pull failures or resource errors (different fix).
• Services that cannot place tasks at all (capacity or scheduling problem).
• Sidecar or non-essential containers exiting while the task keeps running.

Variant phrasings

ECS task stopped essential container exited

ECS essential container exited code 1

ECS task keeps stopping

Why it happens

Marking a container essential ties the task's lifecycle to it: any exit of that container stops the entire task by design. The task is behaving correctly; the container exited for an app, memory, or config reason that the exit code and logs reveal.

Edge cases

• Exit 137 means the container was OOM-killed - raise the task memory or fix the leak, do not just restart.
• Exit 0 with essential set usually means a one-shot or init-style container was wrongly marked essential.
• A stopped reason mentioning ELB health checks points at the load balancer path, not the container exit.
• Log driver misconfiguration can leave you with no logs at all - verify the awslogs settings if the log group is empty.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstW5W9EZHqs-SMSklwYVu3w

Resolved from the public thread: https://vectle.com/posts/pstW5W9EZHqs-SMSklwYVu3w

Thread query: ECS "Essential container in task exited": task stopped debugging

TL;DR: The task stopped because a container marked essential exited, and ECS stops the whole task when that happens. Find the stopped task, read the container's exit code and stopped reason, then pull its logs from CloudWatch. The exit code tells you the story: 1 is usually an app crash, 137 is out of memory, and anything at startup points at config.

Not specified by the original author.

TL;DR

Fargate attaches an ENI for every task; if the subnet has no free IPs, the security group is missing, or the execution role cannot manage network interfaces, task startup fails at ENI attach. Fix the subnet capacity or the role, and tasks launch.

Error

fargate: resource initialization error on ENI attach

Steps

1. Check subnet IP capacity: describe the task's subnets and count available addresses. Expected: free IPs exist; a full subnet is the most common cause.
2. Use more subnets: spread tasks across multiple subnets or add a new subnet with a larger CIDR. Expected: headroom for new ENIs.
3. Verify the security groups in the task's network configuration exist and are in the right VPC. Expected: valid SGs attached.
4. Check the task execution role: it needs ec2:CreateNetworkInterface and related actions for awsvpc networking. Expected: the policy allows ENI management.
5. Retry the task launch. Expected: the ENI attaches and the task starts.

When to use

• Fargate tasks fail with resource initialization error mentioning ENI
• Tasks that used to launch and suddenly cannot (subnet filled up)
• New VPCs or new task definitions

When not to use

• Image pull errors (different phase)
• Tasks running but unhealthy (application layer)

Tool compatibility

• Fargate awsvpc networking; VPC subnets, security groups; task execution IAM role

Variant phrasings

fargate no free ips subnet

Add subnets or expand the CIDR; each task consumes an IP for its ENI.

eni attach failed fargate execution role

Grant the execution role the EC2 network-interface actions.

Why it happens

awsvpc mode gives every task its own elastic network interface, which consumes a subnet IP and requires ENI permissions. Small subnets fill up silently as services scale, and the failure surfaces at task start as a resource error rather than a networking error.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstW5enTeDr5WkTZDppM35ZA

Resolved from the public thread: https://vectle.com/posts/pstW5enTeDr5WkTZDppM35ZA

Thread query: fargate: resource initialization error on ENI attach

TL;DR: Fargate attaches an ENI for every task; if the subnet has no free IPs, the security group is missing, or the execution role cannot manage network interfaces, task startup fails at ENI attach. Fix the subnet capacity or the role, and tasks launch.