Amazon ECS on Fargate errors
Look up why an ECS Fargate task failed to register, start or keep running — ResourceInitializationError and CannotPullContainerError variants, invalid CPU/memory, stopped reasons and container exit codes — each with cause and fix.
markdownreferencev4KY1N-FSK2stage: operatetrust: officialservice: ecsinterface: anyResourceInitializationErrorunable to pull secrets or registry authexecution resource retrieval failedCannotPullContainerErrorfailed to resolve refrequest canceled while waiting for connectiontoomanyrequestsno space left on devicepull access deniedcontext canceledfailed to initialize logging driverInvalid 'cpu' setting for taskNo Fargate configuration exists for given valuesEssential container in task exitedexit code 137exit code 139exit code 255Task failed ELB health checks
Read stoppedReason and each container's reason and exitCode with aws ecs describe-tasks within an hour of the stop. After that, the task is gone from the API. Errors before your code starts (ResourceInitializationError, CannotPullContainerError) are about the execution role or the network path. Exit codes are about your container.
Fargate platform 1.4 truncates long error messages, so match on the leading fragment.
ResourceInitializationError (task never started)
Network check (rows that say no connection or no route): aws ec2 describe-route-tables --filters Name=association.subnet-id,Values=<task-subnet> must show 0.0.0.0/0 to a NAT gateway (private subnet) or an internet gateway (public subnet, with a public IP), or aws ec2 describe-vpc-endpoints --filters Name=vpc-id,Values=<vpc> must list the service's endpoint with the task's security group allowed on 443. Read the message itself with aws ecs describe-tasks --cluster <c> --tasks <task> --query 'tasks[0].[stoppedReason,containers[].reason]'.
| Message (leading fragment) | Cause → fix | Check |
|---|---|---|
unable to pull secrets or registry auth: execution resource retrieval failed / pull command failed: unable to pull secrets or registry auth … Check your task network configuration | The task cannot reach ECR, Systems Manager or Secrets Manager. Route via NAT, a public IP in a public subnet, or VPC endpoints (patterns/ecs-to-ecr.md) | Network check above |
The task cannot pull registry authentication from Amazon ECR | No connection to ECR (ecr.api), as above | Network check above (ecr.api, ecr.dkr) |
The task can't download the environment variable files from Amazon S3 | No route to S3 for environmentFiles: add the S3 gateway endpoint or NAT, and allow s3:GetObject on the execution role (UNVERIFIED permission name in this source) | Network check above (S3 gateway endpoint); aws iam simulate-principal-policy for s3:GetObject on the execution role |
The task cannot pull secrets from AWS Systems Manager Parameter Store | No connection to the ssm endpoint | Network check above (ssm) |
The task can't pull secrets from AWS Secrets Manager | No connection to the Secrets Manager endpoint | Network check above (secretsmanager) |
The task can't pull the secret from Secrets Manager | A network timeout (dial tcp … i/o timeout, context deadline exceeded), or the execution role lacks secretsmanager:GetSecretValue (and kms:Decrypt for a customer managed key), or the secret ARN does not exist | Network check above; then aws iam simulate-principal-policy --policy-source-arn <exec-role> --action-names secretsmanager:GetSecretValue |
The task cannot find the Amazon CloudWatch log group defined in the task definition | No connection to the logs endpoint | Network check above (logs) |
failed to initialize logging driver | The awslogs-group is wrong or does not exist. Check with aws ecs describe-task-definition, then create the group or fix the name | aws logs describe-log-groups --log-group-name-prefix <awslogs-group> |
failed to invoke EFS utils commands to set up EFS volumes | EFS misconfigured, missing permissions, or no network path to the mount target | aws efs describe-mount-targets --file-system-id <fs>: one in the task's AZ; its security group allows 2049 |
CannotPullContainerError (image not pulled)
The source page was read in a French machine translation. The strings below are the English technical fragments that page preserves.
| Message (fragment) | Cause → fix | Check |
|---|---|---|
… Check that the role has the permissions to pull images from the registry | Image missing from the repository, or the execution role (Fargate) cannot pull. Attach AmazonECSTaskExecutionRolePolicy, and check the repository policy | aws ecr describe-images --repository-name <r> --image-ids imageTag=<t>; the execution role's policies |
… There is a connection issue between the task and Amazon ECR. Check your task network configuration | No route to ECR | Network check above |
pull image manifest has been retried 5 time(s): failed to resolve ref | The tag or digest does not exist (any more). ECS pins image versions at deployment, so a re-pushed or deleted tag breaks running services. Use immutable tags, not :latest | aws ecr describe-images --repository-name <r> --image-ids imageTag=<t> |
API error (500): Get https://<account>.dkr.ecr.<region>.amazonaws.com/v2/: net/http: request canceled while waiting for connection | No route to the internet. Public subnet → assignPublicIp=ENABLED. Private subnet → NAT gateway (or endpoints) | Network check above; aws ecs describe-services → networkConfiguration.awsvpcConfiguration.assignPublicIp |
Error response from daemon: Get <url>: net/http: request canceled while waiting for connection | Same: no route out | Network check above |
context canceled | Usually the VPC has no route to pull from ECR | Network check above |
ref pull has been retried 1 time(s): failed to copy: httpReadSeeker: failed open: unexpected status code | The layer download failed. Usually the S3 gateway endpoint or its route is missing in a private subnet (Knowledge Center: platform 1.4.0 needs ecr.api, ecr.dkr and S3) | Network check above (S3 gateway endpoint and its route-table entry) |
pull command failed: panic: runtime error: invalid memory address or nil pointer dereference | Security group or route table does not allow S3. A gateway endpoint needs a route-table entry | Network check above (S3 gateway endpoint and its route-table entry) |
pull access denied | Registry authentication: for a private non-ECR registry, set repositoryCredentials (a container-definition field in the ECS API model) to a Secrets Manager secret | aws ecs describe-task-definition → containerDefinitions[].repositoryCredentials |
toomanyrequests: … (pull rate limit) | Docker Hub rate limit. Authenticate, or mirror the image to ECR (pull-through cache) | The image URI: docker.io or no registry host means Docker Hub |
write /var/lib/docker/tmp/GetImageBlob…: no space left on device | Image larger than the task's storage. On Fargate, raise ephemeralStorage (20 GiB default, max 200 GiB) | describe-task-definition → ephemeralStorage vs the image size |
Registration errors
Check: aws ecs describe-task-definition --task-definition <td> --query 'taskDefinition.[cpu,memory]' against the valid pairs.
| Message | Fix |
|---|---|
An error occurred (ClientException) when calling the RegisterTaskDefinition operation: Invalid 'cpu' setting for task. | Not a valid Fargate CPU/memory pair (reference/ecs/roles-and-networking.md). Windows supports only 1, 2 or 4 vCPU |
Error: ClientException: No Fargate configuration exists for given values. (Terraform) | Same cause |
Stopped reasons
Check for this table and the next: aws ecs describe-tasks --cluster <c> --tasks <task> --query 'tasks[0].{why:stoppedReason,containers:containers[].{name:name,exit:exitCode,reason:reason}}'. Stopped tasks stay visible for about one hour (guides/ecs/run-fargate-task.md); after that, only the logs remain.
stoppedReason | Meaning |
|---|---|
Essential container in task exited | A container marked essential stopped. Read its exit code and logs |
Task failed ELB health checks | The load balancer marked the target unhealthy. Check the health-check path, port, start-up time and security group from the load balancer |
Failed container health checks | The task definition's healthCheck command failed |
ECS is performing maintenance on the underlying infrastructure hosting the task | Platform retirement. A service replaces the task |
ECS service scaling event triggered | Scale-in |
Task stopped by user | Someone called StopTask: CloudTrail userIdentity shows who |
Container exit codes
| Code | Meaning → what to check |
|---|---|
| 0 | Completed normally. A task that should keep running needs a process that does not exit |
| 1 | Application error: the logs |
| 137 | Killed (SIGKILL): did not stop within 30 s of SIGTERM, or ran out of memory. Handle SIGTERM, raise the memory |
| 139 | Segmentation fault: invalid memory access, sometimes a bad environment variable |
| 255 | ENTRYPOINT/CMD failed: wrong path, missing binary, wrong architecture for the image |
Stopped-task details last one hour. To keep them, capture ECS task state-change events with EventBridge into CloudWatch Logs.
When none of these fits
Read the stopped task's stoppedReason and each container's reason (aws ecs describe-tasks --cluster <c> --tasks <id>), then the service events (aws ecs describe-services …). Search the hub for those strings. If the container started and exited, the answer is in its own logs (reference/cloudwatch/logs-insights-queries.md). If it never started, it's image pull, secrets or networking (patterns/ecs-to-ecr.md).