How can I resolve the Amazon ECR error "CannotPullContainerError: API error" in Amazon ECS?

Short description

You can receive this error due to one of the following issues:

• Your launch type doesn't have access to the Amazon ECR endpoint
• Your Amazon ECR repository policy restricts access to repository images
• Your AWS Identity and Access Management (IAM) role doesn't have the right permissions to pull or push images
• The image can't be found
• Amazon Simple Storage Service (Amazon S3) access is denied by your Amazon Virtual Private Cloud (Amazon VPC) gateway endpoint policy

To pull images, Amazon ECS must communicate with the Amazon ECR endpoint.

Resolution

Your launch type doesn't have access to the Amazon ECR endpoint

1.    If you're running a task using an Amazon Elastic Compute Cloud (Amazon EC2) launch type and your container instance is in a private subnet, or if you're running a task using the AWS Fargate launch type in a private subnet, confirm that your subnet has a route to a NAT gateway in the route table.

2.    If you're running a task using an EC2 launch type and your container instance is in a public subnet, then confirm that the instance has a public IP address.

-or-

If you're running a task using the Fargate launch type in a public subnet, then choose ENABLED for Auto-assign public IP when you launch the task. This allows your task to have outbound network access to pull an image.

3.    Configure the NAT gateway in your VPC to route requests to the internet.

Note: You can use AWS PrivateLink as an alternative to a NAT gateway.

4.    If you're using AWS PrivateLink for Amazon ECR, then confirm that the security group that's associated with the interface VPC endpoints for Amazon ECR allows inbound traffic over HTTPS (port 443) from within the security group of your VPC CIDR, ECS container instance, or Fargate task or service.

5.    Confirm that the security group attached to your instance and Fargate task allows outbound access for the following: HTTPS on port 443, DNS (UDP and TCP) on port 53, and your subnet's network access control list (network ACL).

Your Amazon ECR repository policy restricts access to repository images

Check your Amazon ECR repository policy for restrictions on accessing the repository.

The following repository policy example allows IAM users to push and pull images:

{
  "Version": "2008-10-17",
  "Statement": [
    {
      "Sid": "AllowPushPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::123456789012:user/push-pull-user-1",
          "arn:aws:iam::123456789012:user/push-pull-user-2"
        ]
      },
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:BatchCheckLayerAvailability",
        "ecr:PutImage",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload"
      ]
    }
  ]
}

Your IAM role doesn't have the right permissions to pull images

If you're running a task using an EC2 launch type, then confirm that the instance IAM role associated with the instance profile has permissions to access the Amazon ECR repository.

Note: The AWS managed policy AmazonEC2ContainerRegistryReadOnly provides the minimum permissions required to pull images.

If you're running a task using a Fargate launch type, then confirm that the AmazonECSTaskExecutionRolePolicy has the required permissions.

The image can't be found

To confirm the correct image name in the URI, check the image parameter in the container definitions section of your task definition.

Note: To pull by tag, use the following image name format: registry/repository[:tag]. To pull by digest, use the registry/repository[@digest] format.

Amazon S3 access is denied by your Amazon VPC gateway endpoint policy

If you have a route to an Amazon VPC gateway endpoint for Amazon S3 in the route table, then complete the following:

1.    Verify the access policy of the Amazon VPC gateway endpoint.

2.    Confirm that the Amazon VPC gateway endpoint has the correct policy to access the S3 bucket.

Related information

CannotPullContainer task errors