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

Last updated: 2020-11-03

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 cause tasks not to start. 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.


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 through an internet gateway, NAT gateway, or VPC endpoints.

If you're not using AWS PrivateLink, 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 ( of the route table enables 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 enables 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: Only Amazon ECS tasks that use the Fargate launch type and platform version 1.3.0 or earlier require the com.amazonaws.region.ecr.dkr VPC endpoint for Amazon Elastic Container Registry (Amazon ECR) and the Amazon Simple Storage Service (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 should be on the list of subnets and associated with the Fargate subnets. You should 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, and 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.
  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, make sure that you see image:tag in the specified image repository.

Did this article help?

Do you need billing or technical support?