CloudConsole

ResourceInitializationError: unable to pull secrets or registry auth

Updated 17 November 2026 · How we write and check guides

Short answer

Before starting your container, ECS couldn't fetch something it needs on the task's behalf: secrets from Secrets Manager or Parameter Store, or the ECR authorisation token. The cause is almost always either no network path from the task's subnets to those services, or a task execution role missing secretsmanager:GetSecretValue, ssm:GetParameters or kms:Decrypt for the referenced secret.

On this page, in 4 steps: 1. What the message looks like; 2. Causes and fixes; 3. Check the task definition; 4. Networking…
The diagnosis and fix steps from this page, in the order to try them; commands and details are below.

What the message looks like

ResourceInitializationError: unable to pull secrets or registry auth: execution resource
retrieval failed: unable to retrieve secret from asm: service call has been retried 5 time(s):
failed to fetch secret arn:aws:secretsmanager:eu-west-2:123456789012:secret:prod/db-AbCdEf
from secrets manager: … i/o timeout

The middle tells you which service: asm is Secrets Manager, ssm is Parameter Store, and a registry-auth variant names ECR. The ending tells you why: a timeout means networking, AccessDeniedException means permissions, ResourceNotFoundException means the reference is wrong.

Causes and fixes

EndingCauseFix
i/o timeout / context deadline exceededTask subnets can't reach the service endpointNAT gateway, public IP for Fargate in public subnets, or VPC endpoints
AccessDeniedExceptionExecution role lacks secretsmanager:GetSecretValue or ssm:GetParametersGrant them on the specific ARNs
KMS access deniedSecret encrypted with a customer managed key the execution role can't useGrant kms:Decrypt on that key
ResourceNotFoundExceptionWrong ARN, wrong region, or a secret that was deletedUse the full ARN from describe-secret
Invalid JSON key or versionBad valueFrom suffix for a JSON keyUse arn…:secret:prod/db-AbCdEf:password::

The execution role is the one in executionRoleArn; the task role (taskRoleArn) isn't used for this step. Secrets are fetched once when the task starts, so a rotated secret only reaches the container when the task is replaced.

Check the task definition

aws ecs describe-task-definition --task-definition api \
  --query 'taskDefinition.{exec: executionRoleArn, secrets: containerDefinitions[].secrets[]}'

Example of correct references for a whole secret, one JSON key from a secret, and a Parameter Store parameter:

"secrets": [
  { "name": "DB_SECRET",   "valueFrom": "arn:aws:secretsmanager:eu-west-2:123456789012:secret:prod/db-AbCdEf" },
  { "name": "DB_PASSWORD", "valueFrom": "arn:aws:secretsmanager:eu-west-2:123456789012:secret:prod/db-AbCdEf:password::" },
  { "name": "API_URL",     "valueFrom": "arn:aws:ssm:eu-west-2:123456789012:parameter/prod/api-url" }
]

A matching execution role policy:

{ "Effect": "Allow",
  "Action": ["secretsmanager:GetSecretValue", "ssm:GetParameters"],
  "Resource": ["arn:aws:secretsmanager:eu-west-2:123456789012:secret:prod/db-*",
               "arn:aws:ssm:eu-west-2:123456789012:parameter/prod/*"] }

Networking for private subnets

Without NAT, the task's subnets need interface endpoints for each service the task definition uses: secretsmanager, ssm, ecr.api, ecr.dkr, logs, plus the s3 gateway endpoint for image layers, and kms if a customer managed key is involved. Their security groups must accept HTTPS from the tasks.

Other ResourceInitializationError variants have the same flavour: failed to validate logger args usually means the awslogs log group doesn't exist (create it, or set awslogs-create-group with permission to create it), and EFS mount failures point at mount targets or security groups for NFS.

Questions

What is ResourceInitializationError in ECS?

ECS couldn't prepare resources a task needs before its containers start, such as secrets, the ECR auth token, the log group or EFS volumes. The task stops without running your code.

Which IAM role needs access to secrets in ECS?

The task execution role. It needs secretsmanager:GetSecretValue or ssm:GetParameters on the referenced ARNs, and kms:Decrypt if a customer managed key encrypts them.

How do I reference a JSON key from Secrets Manager in ECS?

Append the key to the secret ARN in valueFrom, in the form arn:…:secret:name-AbCdEf:jsonKey:: with empty version stage and version ID.

CloudConsole ECS service screen on a phone, for following up on ResourceInitializationError away from your desk
When this happens away from your desk

This error tends to start after a networking or secrets change, and it stops every new task from launching. CloudConsole, a phone app for AWS, is built to show service events and alarms on your phone so you notice before running tasks are replaced.

Did it start after a deploy? What changed? on the app’s alarm screen lists the deploys and configuration changes from the hour before the alarm fired.

About the app → · Download on the App Store

Sources