You deploy a service on Amazon ECS (Amazon's service for running containers). The task tries to start, then stops before your app runs. The stopped reason says ResourceInitializationError.

Think of a new employee on their first day. Before they can work, someone must hand them a badge, keys and a laptop. If the badge office is closed, or the keys are in the wrong building, they cannot start. ResourceInitializationError means one of those handovers failed before your app even ran. For background, see What is Amazon ECS?.

Fastest fix path: read the full stopped reason, match it in the table below, and check the network first.

Quick answer

  • The error means Fargate could not set up something your task needs before starting your app.
  • AWS documents 9 versions of this message. 6 point straight at a connection problem, and 2 more list the network as one possible cause.
  • Check the network first: a public IP with an internet gateway, a NAT gateway, or VPC endpoints.
  • Next, check the task execution role. It needs extra permissions for secrets, env files and log groups.
  • Then check what the task points to: the secret ARN, the Region, the log group, the S3 file or the EFS volume.
  • Fix it, force a new deployment, and read the next stopped reason.

Quick error message lookup

AWS has reworded some stopped-task messages over time, so your exact text can differ slightly. Match on the key part.

If the message contains Most likely cause Go to
unable to pull secrets or registry auth Network path blocked to ECR, Parameter Store or Secrets Manager Cause 1
unable to retrieve secret from asm Network, role permission or wrong secret ARN (asm means AWS Secrets Manager) Cause 1, 2, 3
dial tcp, dial udp, i/o timeout, net/http: TLS handshake timeout, read: connection timed out, Client.Timeout exceeded while awaiting headers, net/http: request canceled while waiting for connection, signal: killed, context deadline exceeded Network problem Cause 1
AccessDeniedException or is not authorized to perform Execution role lacks a permission Cause 2
Check whether the secret exists in the specified Region Wrong ARN, wrong Region or deleted secret (timeouts in the same line mean network, AccessDenied means permissions) Cause 3
failed to validate logger args or failed to initialize logging driver Missing log group or wrong name Cause 4
failed to validate logger args: : signal: killed Network timeout to the logs service Cause 1
failed to download env files: file download command: non empty error stream S3 file, permission or network problem Cause 5
failed to invoke EFS utils commands to set up EFS volumes EFS setup, permissions or network Cause 6

Key words in simple English

  • ECS: Amazon Elastic Container Service. It runs your containers for you.
  • Fargate: a mode of ECS where AWS manages the servers. You only describe the container.
  • Task: one running copy of your app, made of one or more containers.
  • Task definition: the recipe for a task. It lists the image, memory, secrets and log settings.
  • Task execution role: an AWS identity used by ECS and Fargate to do setup work for your task, such as fetching secrets.
  • Task role: an AWS identity used by your own app code while it runs.
  • VPC: your private network inside AWS.
  • Subnet: a slice of a VPC. A public subnet has a direct route to the internet. A private subnet does not, but it can reach out through a NAT gateway.
  • Internet gateway: the door that lets a public subnet talk to the internet.
  • NAT gateway: a helper that lets private resources reach the internet, but blocks traffic coming in.
  • VPC endpoint: a private door from your VPC to one AWS service, with no internet needed.
  • Security group: a firewall attached to a resource. You list the traffic it allows, by port and source. Everything else is blocked.
  • Network ACL: a firewall for a whole subnet. It does not remember connections, so you must allow both directions.
  • Secrets Manager: an AWS service that stores passwords and keys safely.
  • Parameter Store: a part of AWS Systems Manager that stores settings and small secrets.
  • ARN: Amazon Resource Name. It is the full unique address of an AWS thing.
  • CloudWatch Logs: where your container's log output is stored.
  • EFS: Amazon Elastic File System. A shared network disk that containers can mount.

First, get the full error message

In simple words: the short text in a list view is often cut off. You need the full stopped reason, because it names the exact step that failed.

In the console, do this:

  1. Open the ECS console and choose Clusters.
  2. Choose your cluster and open the Tasks tab.
  3. Set the desired status filter to Stopped.
  4. Choose the task and read the stopped reason.

Stopped tasks only appear in the console for 1 hour. Check soon after the failure.

You can also use the CLI:

aws ecs list-tasks --cluster my-cluster --desired-status STOPPED aws ecs describe-tasks --cluster my-cluster --tasks <task-id> --query 'tasks[0].{stopCode:stopCode,reason:stoppedReason}' 

The stoppedReason field holds the full ResourceInitializationError: ... text. The stopCode field is a short code. For this error you will usually see TaskFailedToStart.

The other valid stop codes are EssentialContainerExited, UserInitiated, ServiceSchedulerInitiated, SpotInterruption, TerminationNotice and InfrastructureHealth. For a service, the service events also show these failures.

Let AWS check it for you: the AWSSupport-TroubleshootECSTaskFailedToStart runbook

In simple words: AWS ships a ready-made checklist robot for this exact problem. You give it your cluster and the failed task, and it tests the likely causes.

The runbook is called AWSSupport-TroubleshootECSTaskFailedToStart. It is an AWS Systems Manager Automation runbook, which means a scripted set of troubleshooting steps. AWS's own connectivity guide recommends it.

It needs two inputs: the cluster name and the ID of the most recent failed task. An assume role is optional. It must run in the same AWS Region as the failed task.

It checks these areas:

  • Network connectivity to the configured container registry.
  • Missing task execution role permissions.
  • VPC endpoint connectivity.
  • Security group rules.
  • Secrets Manager secret references.
  • Logging configuration.

To test connectivity, it may create a temporary Lambda function and IAM role, then delete them. If the delete fails, you remove them yourself.

To use it, open Automation in the Systems Manager console and search for the runbook name.

If you are not hands-on with AWS, the Quick answer and the lookup table above tell you what to ask your team to check. The six causes below are step by step for engineers.

Cause 1: The task cannot reach AWS services (network)

In simple words: before your app starts, the task must call several AWS services. If it has no path out of the VPC, those calls time out and the task dies.

Most of AWS's documented messages for this error point here. Since Fargate platform version 1.4.0, the task gets a single network interface (the "task ENI"). All its traffic goes through your VPC, including the ECR login and fetching secrets.

On version 1.3.0, a separate Fargate-owned interface handled some of this. That is why setups that worked on 1.3.0 could fail after moving to 1.4.0 or later.

A Fargate task needs one of these paths out:

  1. Public subnet: auto-assign public IP set to ENABLED (assignPublicIp ENABLED in the service network configuration), plus a route 0.0.0.0/0 to an internet gateway.
  2. Private subnet with NAT: public IP DISABLED, plus a route 0.0.0.0/0 to a NAT gateway.
  3. Private subnet with no NAT: VPC endpoints for each service the task uses.

VPC endpoints you may need

Replace us-east-1 with your own Region.

Endpoint Type Needed when
com.amazonaws.us-east-1.ecr.api Interface Pulling images from ECR (platform 1.4.0+ needs both ECR endpoints)
com.amazonaws.us-east-1.ecr.dkr Interface Pulling images from ECR (private DNS must be enabled on this one)
com.amazonaws.us-east-1.s3 Gateway ECR stores image layers in S3. Also needed for env files in S3
com.amazonaws.us-east-1.logs Interface The awslogs log driver (CloudWatch Logs)
com.amazonaws.us-east-1.secretsmanager Interface Secrets from Secrets Manager
com.amazonaws.us-east-1.ssm Interface Parameters from Parameter Store

The S3 gateway endpoint must be added to the route tables of your private subnets. If you use an endpoint policy on it, allow this resource:

arn:aws:s3:::prod-us-east-1-starport-layer-bucket/* 

Fargate tasks do not need the Amazon ECS interface endpoints.

List the endpoints in your VPC with:

aws ec2 describe-vpc-endpoints --filters Name=vpc-id,Values=vpc-0abc1234 --query 'VpcEndpoints[].ServiceName' 

Firewall and DNS rules

  • The endpoint's security group must allow inbound TCP 443 from the task's private subnet.
  • The task's security group needs outbound HTTPS 443.
  • Network ACLs are stateless, so allow HTTPS 443 and the return ports 1024-65535 in both directions as needed.
  • Turn on Private DNS for the interface endpoints. The VPC needs both enableDnsSupport and enableDnsHostnames.
  • VPC endpoints only work through Amazon-provided DNS (Route 53 Resolver). If you run your own DNS server, allow outbound port 53 (UDP and TCP) to it, and make it forward AWS names to the Amazon-provided DNS.

If the image pull itself is failing, read the CannotPullContainerError guide. It shares this same network root cause.

Cause 2: The task execution role is missing permissions

In simple words: the task needs a "setup helper" identity with the right permissions. If that helper is not allowed to fetch your secret, the task fails at startup.

There are two roles, and people mix them up often:

  • The task execution role is used by the ECS and Fargate agents. It pulls the ECR image, fetches secrets, downloads env files and sends awslogs logs. In the task definition the field is executionRoleArn.
  • The task role is used by your app code. The execution role's permissions are not available to your containers.

A common mistake is adding secret permissions to the task role instead of the execution role. The execution role must also trust the service principal ecs-tasks.amazonaws.com.

The AWS managed policy AmazonECSTaskExecutionRolePolicy grants exactly these actions: ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:GetDownloadUrlForLayer, ecr:BatchGetImage, logs:CreateLogStream and logs:PutLogEvents. It has nothing for Secrets Manager, Parameter Store, KMS or S3.

Add what you need on top:

Permission Add it when
secretsmanager:GetSecretValue You inject Secrets Manager secrets
ssm:GetParameters You inject Parameter Store values
kms:Decrypt The secret or parameter uses a customer managed KMS key, not the default key
s3:GetObject on the file, plus s3:GetBucketLocation on the bucket You use env files
logs:CreateLogGroup You turn on awslogs-create-group

Secrets Manager adds a hyphen and six random characters to the end of every secret ARN. In an IAM policy, use the full ARN, or match the suffix with -?????? (each ? matches one character). A Resource without the suffix will not match.

Here is an example policy:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/db-??????" }, { "Effect": "Allow", "Action": "ssm:GetParameters", "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/my-app/*" } ] } 

A permission problem usually shows AccessDeniedException or is not authorized to perform in the message. A network problem shows timeouts instead.

Cause 3: The secret ARN or name is wrong

In simple words: the task definition points to a secret by address. If the address is wrong, in the wrong Region, or the secret is gone, the task cannot fetch it.

For Secrets Manager, the valueFrom field should be the full ARN of the secret. For Parameter Store, the parameter name works in the same Region. A parameter in a different Region needs the full ARN. Using the full ARN everywhere avoids doubt.

To pick one JSON key from a secret, the format is:

arn:aws:secretsmanager:region:account:secret:name-AbCdEf:json-key:version-stage:version-id 

Keep the colons for the parts you skip. For example:

arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/db-AbCdEf:password:: 

You can set a version stage or a version ID, not both. The default stage is AWSCURRENT.

Check these points:

  • The Region in the ARN is where the secret really lives. AWS's own message says to check the secret exists in the specified Region. The simplest setup keeps secrets in the same Region as the task.
  • The secret is not deleted. A deleted secret, or one scheduled for deletion, cannot be fetched.

These safe checks do not print the secret value:

aws secretsmanager describe-secret --secret-id arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/db-AbCdEf aws ssm get-parameter --name /my-app/db-password --query Parameter.ARN 

Secrets are injected when the container first starts. After you change a secret, start new tasks. For a service, run:

aws ecs update-service --cluster my-cluster --service my-service --force-new-deployment 

Cause 4: The CloudWatch log group is missing

In simple words: your container sends its output to a named log folder. If that folder does not exist, the task refuses to start.

The messages failed to initialize logging driver and failed to validate logger args usually mean the log group in the task definition does not exist, or its name is wrong. If the message says it cannot find the log group because of a connection issue, it is the network instead. In that case check the logs endpoint from Cause 1.

Look at your task definition:

aws ecs describe-task-definition --task-definition my-app 

In the output, find each container's logConfiguration and read the awslogs-group and awslogs-region options. Make sure the group exists in that Region.

There are two fixes.

Fix A: create the group in the right Region.

aws logs create-log-group --log-group-name /ecs/my-app --region us-east-1 

Fix B: let ECS create it. Set this in the awslogs options (the default is false):

"awslogs-create-group": "true" 

Then add logs:CreateLogGroup to the execution role.

Cause 5: The env file cannot be downloaded from S3

In simple words: an env file is a small settings file stored in S3. The task must be allowed to read it and be able to reach S3.

Env files are set with environmentFiles in the task definition. These rules apply:

  • The file must use the .env extension and UTF-8 encoding.
  • Use one VARIABLE=VALUE per line. Lines starting with # are comments.
  • You can use up to 10 files per task definition.
  • On Fargate they need platform version 1.4.0 or later (Linux). Windows containers cannot use environmentFiles.

The execution role needs s3:GetObject on the file and s3:GetBucketLocation on the bucket. In a private subnet with no NAT, the S3 gateway endpoint must be in place.

Check that the file exists:

aws s3 ls s3://my-config-bucket/my-app/app.env 

AWS recommends Secrets Manager or Parameter Store, not env files, for sensitive values.

Cause 6: The EFS volume cannot be mounted

In simple words: EFS is a shared network disk. The task must be able to find it, reach it on the right port, and be allowed to use it.

Check these points in order:

  • EFS on Fargate needs platform version 1.4.0 or later (Linux).
  • The EFS mount target's security group needs an inbound rule for NFS, TCP port 2049, from the task's security group.
  • The file system needs a mount target in each Availability Zone where your tasks run. Its DNS name only resolves in an AZ that has a mount target.
  • The VPC needs DNS resolution and DNS hostnames enabled, and must use Amazon-provided DNS.

If you set authorizationConfig iam to ENABLED, ECS mounts with the task role, not the execution role. In that case transitEncryption must be ENABLED. Using an access point also requires transit encryption.

The task role then needs EFS client permissions such as elasticfilesystem:ClientMount, and elasticfilesystem:ClientWrite to write.

For more help, see AWS re:Post: Why can't I mount my Amazon EFS volumes on my AWS Fargate tasks?

A fast checklist, in order

  1. Read the full stopped reason, not the short one.
  2. Run the AWSSupport-TroubleshootECSTaskFailedToStart runbook in the same Region.
  3. Match the message in the lookup table.
  4. Check the network path for your subnet type: public IP and internet gateway, NAT gateway, or VPC endpoints.
  5. Check the execution role, not the task role.
  6. Check the reference: the ARN, the Region, the log group, the S3 file or the EFS setup.
  7. Fix it, force a new deployment, and watch the next task.

ResourceInitializationError vs CannotPullContainerError

In simple words: both stop a task before your app runs. One fails during setup, the other fails while getting the image.

ResourceInitializationError CannotPullContainerError
When it happens While Fargate sets up what the task needs While pulling the image itself
Typical causes Registry login, secrets, logs, env files, volumes Wrong tag, wrong architecture, rate limits, layer download
Shared root cause Often the network Often the network

This guide focuses on Fargate. Tasks on EC2 instances can fail for the same network and permission reasons.

If a service uses the deployment circuit breaker, tasks that keep failing to start can make the deployment roll back. See the rolling deployment guide.

How to prevent it next time

  • Pick one tested network setup for every Fargate service: NAT, or the full set of endpoints.
  • Give each app its own least-privilege execution role, with specific ARNs.
  • Use full ARNs for secrets and parameters.
  • Create log groups in your infrastructure code, or use awslogs-create-group.
  • Add an EventBridge rule that sends ECS task state change events to CloudWatch Logs. This keeps stopped reasons longer than the console's 1 hour.
  • Turn on the deployment circuit breaker so bad releases roll back on their own.

Frequently asked questions

What does ResourceInitializationError mean in ECS?

It means an ECS task stopped before your app ran, because Fargate could not set up something the task needs. That can be a registry login, a secret, a log group, an env file or a volume. The full stopped reason tells you which one.

What does "unable to pull secrets or registry auth" mean?

The task could not fetch its ECR login or its secrets at startup. AWS lists a blocked network path to ECR, Systems Manager or Secrets Manager as the cause. Start with Cause 1, then check the execution role.

Why did it start after moving to Fargate platform version 1.4.0?

From 1.4.0, the task has one network interface and all its traffic goes through your VPC. On 1.3.0, a separate Fargate-owned interface handled some of this. A subnet with no route out, or missing endpoints, now causes failures.

What is the difference between the task role and the task execution role?

The execution role is used by ECS and Fargate to set up the task, such as pulling the image and fetching secrets. The task role is used by your app code while it runs. Secret permissions for injection belong on the execution role.

Do I need a NAT gateway?

Not always. You can use a public subnet with a public IP and an internet gateway. You can also stay in a private subnet and add VPC endpoints for each service the task uses. A NAT gateway is the simplest private option.

Why does the error end with "signal: killed"?

AWS lists signal: killed as a sign of a network problem. With failed to validate logger args, it points to a network timeout to the logs service. Check the logs endpoint or your route out.

Why can't I see my stopped task anymore?

Stopped tasks only appear in the console for 1 hour. To keep the reasons longer, send ECS task state change events to CloudWatch Logs with an EventBridge rule.

I changed my secret, why does my app still see the old value?

Secrets are injected when the container first starts. Start new tasks to pick up the change. For a service, run aws ecs update-service --cluster my-cluster --service my-service --force-new-deployment.

Does this happen on the EC2 launch type too?

Yes, it can. Tasks on EC2 instances can fail for the same network and permission reasons. AWS's connectivity guide covers the EC2 subnet and public IP settings too.

Where to go next

Sources: Troubleshooting ResourceInitializationError, Verifying stopped task connectivity, Viewing stopped task errors, Task execution IAM role, Fargate task networking, Amazon ECR interface VPC endpoints, Secrets Manager secrets in ECS, Environment files, EFS volume configuration, AWSSupport-TroubleshootECSTaskFailedToStart runbook.

Last updated: November 22, 2026. I will update this page when AWS changes these messages or the Fargate networking rules.