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

Last updated: 2019-07-18

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, confirm that your subnet has a route to a NAT gateway in the route table. Or, if you're running a task using the AWS Fargate launch type, specify DISABLED for the Auto-assign public IP when you launch the task.

Important: Your instance must not have a public IP address.

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

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?