PacketSensei

AWS `ResourceInitializationError`: What It Means and How to Fix It

PacketSensei

ResourceInitializationError is a Fargate task that cannot reach Secrets Manager, SSM, or ECR before it starts. It comes from ECS Fargate, and the message reads:

ResourceInitializationError: unable to pull secrets or registry auth: execution resource retrieval failed

If you are here mid-incident, skip to how to tell which cause you have — the command there narrows it down faster than reading the list.

Quick reference
Error ResourceInitializationError
Service ECS Fargate
Message ResourceInitializationError: unable to pull secrets or registry auth: execution resource retrieval failed
Most common cause No network path to Secrets Manager or SSM

What it actually means

Fargate resolves secrets and registry credentials before the container starts, using the execution role and the task’s own network path. If either is wrong, the task fails during initialisation with nothing in the application logs, because the application never ran.

The distinguishing feature versus CannotPullContainerError is timing: this failure happens while resolving secrets or repositoryCredentials entries in the task definition, not while pulling image layers.

Why it happens

Ranked by how often each one turns out to be the answer.

# Cause Fix
1 No network path to Secrets Manager or SSM A private subnet needs a NAT gateway or interface endpoints for secretsmanager and ssm. The task cannot start without them, so there are no logs to read.
2 The execution role cannot read the secret Add secretsmanager:GetSecretValue for the specific secret ARN, or ssm:GetParameters for parameters. On the execution role, not the task role.
3 The secret is encrypted with a customer-managed KMS key The execution role also needs kms:Decrypt on that key, and the key policy must permit it.
4 A secret ARN from another region or account Secrets are regional. A copied task definition referencing another region’s ARN fails here.
5 A JSON key that does not exist Referencing arn:...:secret:my-secret:username:: requires a username key in the JSON. A missing key fails initialisation rather than producing an empty value.

How to tell which one you have

# Full stopped reason
aws ecs describe-tasks --cluster my-cluster --tasks <task-id> \
  --query 'tasks[].[stoppedReason,stopCode]' --output text

# Can the execution role read it? Simulate as that role.
aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::111122223333:role/ecsTaskExecutionRole \
  --action-names secretsmanager:GetSecretValue \
  --resource-arns 'arn:aws:secretsmanager:eu-west-1:111122223333:secret:my-secret-AbCdEf'

# Which endpoints exist in the task's VPC?
aws ec2 describe-vpc-endpoints --filters Name=vpc-id,Values=vpc-0123456789abcdef0 \
  --query 'VpcEndpoints[].ServiceName' --output text

Preventing it

Remember which role does what: the execution role is used by the Fargate agent to pull images and resolve secrets before start; the task role is used by your application at runtime. Writing that in a comment above both role definitions in your IaC saves a recurring hour.

For private subnets, provision the endpoint set as a unit — ecr.api, ecr.dkr, s3, logs, secretsmanager, ssm — rather than adding them one incident at a time.

Quota codes, limits and behaviour on this page were last checked against AWS documentation on 2026-08-22. AWS changes these; if something here does not match what you are seeing, trust the console and tell us.