Fargate CannotPullContainerError: Match the Image, Execution Role and Layer Path

Classify an existing private-ECR image-pull failure on Fargate Linux without replacing the image, broadening permissions or launching another task.

Primary sources checked 2026-10-18

Bind the failed pull to the task that attempted it

For an existing Fargate CannotPullContainerError, identify the stopped task, the requested image and the role and network path used to retrieve it. Then classify the evidence as image availability, authorization, connectivity or unresolved. Restarting the service or adding permissions before that binding can hide the original failure and launch more work without testing the explanation.

AWS groups several image-retrieval failures under its CannotPullContainer error guidance. The top-level error name is not a unique IAM diagnosis. Keep the complete available message and container context, while removing credentials and signed URLs from shared copies. Some Fargate error messages can be truncated, so a missing suffix is not evidence that an omitted condition did not occur.

The worked scope is Fargate Linux platform 1.4.0 or later, IPv4 networking, a private ECR repository in the same account and Region, and an existing task execution role. The private-endpoint branch assumes an already configured endpoint design. Exclude EC2-hosted tasks, Windows foreign layers, cross-account repositories, ECR Public, pull-through-cache first pulls, FIPS and dual-stack configurations from the examples. They can have additional identity or connectivity requirements. Unknown scope goes to the platform owner before a conclusion.

This guide collects existing metadata and retained observations only. It does not authenticate to a registry, download an image, launch a task, execute a command or change AWS resources. The three worked records are constructed examples rather than account output or client results.

Preserve task identity and the requested artifact

Record the account, Region, explicit cluster, task identity, task-definition revision, named container and task creation, stop and evidence collection times. Retain stop code, stopped reason and container reason where available. The DescribeTasks response also has a failures list: a successful response envelope with a failed item is not a complete task record.

The launch's actual task definition and permitted overrides establish the requested image and relevant role. Do not substitute the newest family revision or a successful neighboring task. For multi-container tasks, identify which container's pull failed. An application image, an observability sidecar and a bootstrap container can use different repositories and failure paths.

Retain the full requested repository identity and whether the reference uses a tag or digest. Use aliases in broadly shared records while keeping the exact identifiers in the approved source. If a digest is present in the retained task or deployment record, preserve it separately from the current tag lookup. A tag that resolves now need not have resolved to the same artifact during the failure.

Current ECR image metadata can corroborate repository, image digest and tags. Its collection time matters. Finding the tag today does not prove historical existence, and not finding it today does not establish the reason for yesterday's failure. Ask the release owner for the retained publication, deployment and lifecycle history that can connect those times.

Separate pulling authority from application authority

On the scoped Fargate path, the task execution role supports agent operations such as pulling the image. The application task role is a different identity. Giving the application role ECR actions is not evidence that the Fargate retrieval path gained the needed authority. AWS explains this separation in task execution role guidance.

Have the IAM owner review the actual execution role and relevant restrictions for registry authentication and image retrieval. The documented ECR action set includes GetAuthorizationToken, BatchCheckLayerAvailability, GetDownloadUrlForLayer and BatchGetImage. Keep actions and resources distinct: a repository permission excerpt alone does not establish token retrieval authority. A policy attached now also does not establish the policy in effect when the task launched.

Effective access can be constrained by more than one allow statement. Record applicable boundaries and explicit-deny evidence, plus repository and endpoint policy context where relevant. Do not publish a universal minimum policy or infer authorization from a successful human registry lookup. The observer's permission to describe images and the service's ability to retrieve them answer different questions.

For a scoped endpoint restriction, compare the actual endpoint identity with the execution role's reviewed conditions. An endpoint replaced during a network change can leave a condition referring to the old one. This is a hypothesis to investigate from retained metadata, not a recommendation to remove the condition. Cross-account access needs a separate combined identity/resource-policy review and remains outside the worked assumptions.

Trace manifest access and layer access as separate dependencies

For the existing private-endpoint design, Fargate platform 1.4.0 or later requires both ECR interface endpoints and an S3 gateway endpoint for private image retrieval. ECR serves registry/API operations, while image layers are stored in S3. Successful manifest access alone does not prove layer delivery. AWS describes the split in its ECR endpoint guide.

The network owner records the task subnet, route-table association, task security group, ECR endpoint identities and security groups, private DNS settings and selected S3 gateway endpoint route tables. Inspect relevant endpoint policies without assuming they replace identity policies. For ECR layers, a policy that permits only the application's own S3 bucket can omit the regional ECR layer bucket. That calls for an exact policy review, not blanket S3 access.

Use existing DNS and flow observations from the task's network context when retained. A route-table screenshot from another subnet cannot prove the task's path. A laptop resolving the public registry name does not establish private DNS behavior inside the task's VPC. A flow accept also does not prove successful TLS, authorization or a complete layer transfer.

Fargate's task networking guidance distinguishes platform behavior and public versus private subnet connectivity. A public subnet label alone does not give a task an internet path. Conversely, a correctly scoped endpoint design should not be replaced by public exposure just because a generic error page mentions internet access. Record the design actually intended and hand inconsistencies to its owner.

Pick the evidence branch before requesting a change

Exact requested digest is not available in the relevant retained publication record

Narrow decision: Investigate artifact identity and retention before changing IAM

Next owner: Release and repository owners

Explicit pull authorization denial tied to the execution role

Narrow decision: Review the denied action and applicable restrictions

Next owner: IAM and repository owners

Manifest obtained but layer transfer timed out on the scoped endpoint design

Narrow decision: Trace the S3 layer path as well as ECR; cause remains provisional

Next owner: Network and endpoint-policy owners

A generic timeout without more context leaves authorization and path hypotheses open. A missing image with incomplete historical records leaves artifact history unknown. The investigation can still produce a useful handoff by naming exactly which observation is missing and who can provide it.

If the error instead concerns secret retrieval, log configuration or another resource-initialization stage, preserve it and use the appropriate initialization procedure. Do not rewrite every failed startup as an ECR incident. A task that starts successfully but cannot establish ECS Exec belongs to the ECS Exec target guide, whose managed-agent channels and task-role permissions are different from this pull boundary.

Worked scenarios: missing artifact, wrong role and incomplete layer route

The aliases and observations here are entirely synthetic. Each record stipulates the supported Fargate/private-ECR scope; none records an AWS operation. Expected interpretations demonstrate how evidence changes the next action, not that a specific repair would succeed.

A: artifact mismatch

Stipulated observations: Task requested digest A; retained release manifest names A; repository history records A removed before launch; current tag names digest B

Decision and next evidence: Artifact A is unavailable under these premises; release owner reconciles retention and approved image identity

B: wrong role assumption

Stipulated observations: Task uses execution role E1; denial names E1 and BatchGetImage; application role T1 has an ECR allow

Decision and next evidence: T1 does not establish E1 authority; IAM owner reviews E1 and the exact denied resource

C: layer route gap

Stipulated observations: Manifest read is stipulated successful; layer transfer times out; task subnet uses route table R2; S3 gateway is associated only with R1; no alternate egress

Decision and next evidence: Scoped layer path has a configuration gap; network owner validates the association and incident evidence before proposing a change

A depends on a retained removal record and its timing. Without that record, a current not-found result would support a weaker conclusion. Repointing the tag to B would change the intended artifact; it would not recover A or prove B is compatible with the application.

B deliberately names the principal and action. If the message supplied neither, the reader could not conclude that E1 caused an explicit denial merely from its existence in the task definition. A full authorization review can still reveal multiple constraints after one is corrected. Copying T1's allow to E1 without checking scope would replace diagnosis with a permission change.

C removes alternate egress as an explicit premise. Without that premise, the missing association would not establish the absence of every possible S3 path. Even within the example, the timeout needs temporal corroboration before declaring the sole incident cause. A route correction proposal should preserve endpoint policy, allowed destinations and unrelated S3 traffic behavior rather than bypassing them.

Keep one launch and retrieval worksheet

Launch and artifact

Incident and release owner, account/Region/cluster/task/container aliases, launch and collection times, platform/OS/address-family scope, task-definition revision, requested reference and retained digest evidence.

Failure

Stop code, complete permitted task and container reasons, truncation or omitted fields, failure stage, request or event references and historical coverage limits.

Authority

Actual execution role, separate application role, denied action/resource when observed, relevant identity/repository/endpoint constraints and configuration times.

Path

Task subnet and route table, ECR API/registry endpoints, private DNS, endpoint security groups, S3 gateway association/policy, intended alternate egress or confirmed absence, existing flow/DNS evidence.

Decision and recovery request

Supported branch, competing explanation, missing observation, next owner, separately approved change boundary and conditions that require renewed review.

Use one row set per failed task rather than merging a series of replacements into a fictional continuous attempt. If the service launches another revision during the investigation, retain the earlier packet and bind the next one to its own role, image and network context. Token values, signed layer URLs and image payloads do not belong in this worksheet.

Failure, recovery and alternatives to another launch

Stop when the task, launch revision or image cannot be bound, the evidence contains credentials, scope is outside this guide or the next diagnostic step would start a real application. An isolated image pull still transfers an artifact, and a task launch can run code with business effects. Neither is authorized by a read-only investigation.

A later reproduction needs an approved isolated account or target, non-sensitive artifact, scoped role and endpoints, inert downstream destinations, bounded resource use and a cleanup owner. Preserve the expected evidence before execution. Do not attach the production application role or real event inputs just to make a new task representative.

For recovery, the release owner chooses an approved artifact and validates compatibility; the IAM or network owner separately approves any needed change. Keep the previous definitions, but recognize that a deleted digest may be unavailable for rollback and an older image may not understand current data. Restoring a route can also affect other traffic. The ECS rollback eligibility article covers the separate question of an eligible completed deployment, not image availability or application correctness.

Your next action is to bind one failed task to one requested image and execution role, then ask the named owner for the first missing retrieval observation. Close the diagnostic handoff with a supported branch or an explicit unresolved gap. Successful application recovery needs a later authorized launch and current application evidence.