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

Last updated: 2019-11-22

When I pull images with Amazon Elastic Container Registry (Amazon ECR), I get the following error: "CannotPullContainerError: API error." How can I resolve this error in Amazon Elastic Container Service (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 your task using an Amazon Elastic Compute Cloud (Amazon EC2) launch type and your container instance is in a public subnet, 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, 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 an AWS PrivateLink as an alternative to a NAT gateway.

4.    If you're using an Amazon provided DNS in your VPC, confirm that the security group attached to the instance and Fargate task has outbound access allowed for HTTPS (443). For a custom DNS, confirm that you have outbound access allowed for DNS (UDP and TCP) on port 53 and HTTPS access on port 443.

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 Amazon EC2 launch type, 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, confirm that the ecsTaskExecutionRole 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.

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, 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.


Did this article help you?

Anything we could improve?


Need more help?