Fargate task stuck in PENDING state due to missing IAM role permissions

Cloud Platforms Amazon Web Services (AWS)
, , , , , , , ,
1

I’m trying to deploy a Fargate task but it’s stuck in PENDING state and never transitions to RUNNING. The task definition references a private ECR repository for the container image. When I check the stopped tasks, I see the error “CannotPullContainerError: pull image manifest has been retried 5 times”.

I’ve verified the image exists in ECR and I can pull it manually using docker login with ECR credentials. The task execution role has the AmazonECSTaskExecutionRolePolicy attached. Here’s what my task definition looks like:


"executionRoleArn": "arn:aws:iam::123456789:role/ecsTaskExecutionRole",
"containerDefinitions": [{
  "image": "123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest"
}]

I’m not sure what’s wrong with the IAM setup. The role has the AWS managed policy, so shouldn’t that be enough for ECR access?

2

The AmazonECSTaskExecutionRolePolicy should cover ECR access, but there might be additional restrictions. Check if your ECR repository has a repository policy that restricts access. Also, make sure your task execution role’s trust policy allows ecs-tasks.amazonaws.com to assume it. Sometimes the trust relationship gets misconfigured during role creation.

3

Make sure you’re also checking CloudWatch Logs for the actual error messages. Enable logging in your task definition with awslogs driver, and you’ll get more detailed error messages that can point to exactly what permission is missing. The generic CannotPullContainerError doesn’t always tell the full story, especially when KMS or cross-account access is involved.

4

I ran into this exact issue last month. The problem was that my ECR repository was encrypted with a custom KMS key, and the task execution role didn’t have permissions to use that key. If you’re using KMS encryption on your ECR repo, you need to add kms:Decrypt permissions to the execution role for the specific KMS key. Check your ECR repository encryption settings in the console.

5

You need to add an inline policy to your task execution role that grants kms:Decrypt permission for your specific KMS key. Also check the KMS key policy itself - it needs to allow the IAM role to use it. Sometimes the key policy is locked down and you need to update both sides. The role policy alone isn’t enough if the key policy explicitly denies access.

6

Good catch Kevin! I checked and yes, the ECR repository is using a custom KMS key for encryption. I didn’t realize that required additional IAM permissions beyond the standard execution role policy. How do I add those KMS permissions to the role?

7

Let me provide a comprehensive solution since this involves multiple IAM components that all need to align correctly.

IAM Execution Role Setup: Your task execution role needs three key permission sets. First, verify the trust policy allows ECS to assume the role:

{
  "Effect": "Allow",
  "Principal": {"Service": "ecs-tasks.amazonaws.com"},
  "Action": "sts:AssumeRole"
}

ECR Image Permissions: The AWS managed policy AmazonECSTaskExecutionRolePolicy covers basic ECR access, but if you’re using KMS encryption (which you are), add this inline policy:

{
  "Effect": "Allow",
  "Action": ["kms:Decrypt", "kms:DescribeKey"],
  "Resource": "arn:aws:kms:us-east-1:123456789:key/your-key-id"
}

KMS Key Policy Configuration: Your KMS key policy must also allow the execution role. Edit the key policy to include:

{
  "Sid": "AllowECSTaskExecution",
  "Effect": "Allow",
  "Principal": {"AWS": "arn:aws:iam::123456789:role/ecsTaskExecutionRole"},
  "Action": ["kms:Decrypt", "kms:DescribeKey"],
  "Resource": "*"
}

Task Definition Configuration: Ensure your task definition properly references the execution role and includes logging for troubleshooting:

"executionRoleArn": "arn:aws:iam::123456789:role/ecsTaskExecutionRole",
"containerDefinitions": [{
  "logConfiguration": {
    "logDriver": "awslogs",
    "options": {
      "awslogs-group": "/ecs/my-app",
      "awslogs-region": "us-east-1"
    }
  }
}]

Verification Checklist:

  1. Confirm execution role has AmazonECSTaskExecutionRolePolicy attached
  2. Add KMS decrypt permissions to execution role (inline policy)
  3. Update KMS key policy to allow execution role
  4. Verify ECR repository policy doesn’t restrict the role
  5. Check that image URI in task definition is correct and includes full path
  6. Enable CloudWatch Logs to see detailed error messages

Common Issues:

  • Cross-account ECR access requires additional repository policies
  • VPC endpoints for ECR must be configured if using private subnets without NAT
  • Image tag must exist (“latest” might not be present)
  • Region mismatch between ECR repository and Fargate task

After updating both the IAM role policy and KMS key policy, create a new task definition revision and launch a new task. The PENDING state should resolve within 30-60 seconds if permissions are correct. Monitor the stopped tasks section - if it still fails, the error message should now be more specific about what’s missing.

The key insight here is that KMS-encrypted ECR repositories require bidirectional permission grants: the IAM role needs KMS permissions, AND the KMS key policy must allow the role. Both must be configured or image pulls will fail.