--- cuppy_hub: aws cuppy_path: reference/ecs/errors.md cuppy_section: docs cuppy_doc: KY1N-FSK2 cuppy_doc_uuid: f18d9afa-0cd2-40a6-8aaa-9130ada547c8 cuppy_permalink: https://cuppy.io/aws/d/KY1N-FSK2 cuppy_version: 4 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/aws/docs/reference/ecs/errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: d6ff676e73c07738e0c3f525ffd2d7150019c01bb6e1614572e21d6c478e0076 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # Amazon ECS on Fargate errors **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=` 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=` 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 --tasks --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 --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 ` | | `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 `: 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 --image-ids imageTag=`; 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 --image-ids imageTag=` | | `API error (500): Get https://.dkr.ecr..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 : 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 --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 --tasks --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 --tasks `), 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`). --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.