How do I resolve the "cannotpullcontainererror" error for my Amazon ECS tasks on Fargate?

Last updated: 2022-08-24

I want to resolve the "cannotpullcontainererror" error so that I can start my Amazon Elastic Container Service (Amazon ECS) tasks on AWS Fargate.

Short description

The "cannotpullcontainererror" error can prevent tasks from starting. To start an Amazon ECS task on Fargate, your Amazon Virtual Private Cloud (Amazon VPC) networking configurations must allow your Amazon ECS infrastructure to access the repository where the image is stored. Without the correct networking, the image can't be pulled by Amazon ECS on Fargate and the container can't start.

Resolution

Confirm that your VPC networking configuration allows your Amazon ECS infrastructure to reach the image repository

The route tables associated to the subnets that your task is created in must allow your Amazon ECS infrastructure to reach the repository endpoint. The endpoint can be reached through an internet gateway, NAT gateway, or VPC endpoints.

If you're not using AWS PrivateLink, then complete the following steps:

  1. Open the Amazon VPC console.
  2. In the navigation pane, choose Subnets.
  3. Select the subnet that your ECS Fargate task is using.
  4. Choose the Route Table tab.
  5. In the Destination column, confirm that the default route (0.0.0.0/0) of the route table allows public internet access. This access can be either through a NAT gateway or an internet gateway.
    Important: The NAT gateway or internet gateway must be the target of the default route. For example route tables, see Example routing options. If you're not using a NAT gateway or internet gateway, then make sure that your custom configuration allows public internet access.

If you're using an internet gateway (public subnets), then confirm that the task has a public IP assigned to it. To do this, launch your ECS task with Auto-assign public IP set to ENABLED in the VPC and security groups section when you create the task or service.

If you're using PrivateLink, confirm that the security groups for your VPC endpoints allow the Fargate infrastructure to use them.

Note: Amazon ECS tasks hosted on Fargate using version 1.3.0 or earlier require the com.amazonaws.region.ecr.dkr Amazon Elastic Container Registry (Amazon ECR) VPC endpoint and the Amazon Simple Storage Service (Amazon S3) gateway endpoint. Amazon ECS tasks hosted on Fargate using version 1.4.0 or later require both the com.amazonaws.region.ecr.dkr and com.amazonaws.region.ecr.api Amazon ECR VPC endpoints and the Amazon S3 gateway endpoint.

  1. Open the Amazon VPC console.
  2. In the navigation pane, choose Endpoints.
  3. Select the endpoint from the list of endpoints, and then choose the Subnets tab. The VPC endpoints com.amazonaws.region.ecr.dkr and com.amazonaws.region.ecr.api for Amazon ECR will display in the list of subnets and associated with the Fargate subnets. You also see the Amazon S3 gateway on the list of subnets.
    Note: If a subnet isn't listed, choose Manage Subnets. Next, select the subnet based on its Availability Zone. Then, choose Modify Subnets.
  4. Choose the Policy tab, and then confirm that the correct policy requirements are met.
  5. To confirm that the security group attached to the com.amazonaws.region.ecr.api and com.amazonaws.region.ecr.dkr VPC endpoints allows incoming connections on port 443 from the Amazon ECS tasks for Fargate, select the endpoint from the list of endpoints.
  6. Choose the Security Groups tab.
  7. For Group ID, choose the security group ID.
  8. Choose the Inbound rules tab, and then confirm that you can see the rule that allows 443 connections from your ECS tasks on Fargate.

Check the VPC DHCP Option Set

  1. Open the Amazon VPC console.
  2. In the navigation pane, choose Your VPCs.
  3. Select the VPC that contains your Fargate task.
  4. On the Details tab, note the setting for DHCP options set.
  5. In the navigation pane, choose DHCP Options Sets.
  6. Select the DHCP options set that you noted in step 4.
  7. Choose Actions, and then choose View details.
  8. Confirm that Domain name servers is set to AmazonProvidedDNS. If it isn't set to AmazonProvidedDNS, then configure conditional DNS forwarding.

Check the task execution role permissions

  1. Open the IAM console. To confirm that the security group attached to the com.amazonaws.region.ecr.api and com.amazonaws.region.ecr.dkr VPC endpoints allows incoming connections on port 443 from the Amazon ECS tasks for Fargate, select the endpoint from the list of endpoints
  2. In the navigation pane, choose Roles.
  3. Select the task execution role that your Fargate tasks are using.
  4. Confirm that the task execution role has the permissions to pull an image from Amazon ECR.

Check that the image exists

  1. Open the Amazon ECR console.
  2. Select the Amazon ECR repository that your Fargate task should be pulling the image from.
  3. Confirm that the URI and the tag in Amazon ECR are the same as what's specified in the task definition.

Note: If you're not using Amazon ECR, then make sure that you see image:tag in the specified image repository.


Did this article help?


Do you need billing or technical support?