How do I troubleshoot Amazon ECS tasks for Fargate that are stuck in the Pending state?

Resolution

Complete the following tasks.

Check what routes to the internet your subnets use

Based on your use case, complete the following tasks:
For Fargate tasks in a public subnet
Verify that your Fargate task has an assigned public IP address and a default route (0.0.0.0/0) to an internet gateway. To verify this, select the Enable auto-assign public IPv4 address check box when you launch your task or create a new service. For more information, see Access the internet.

Note: You can't select the Enable auto-assign public IPv4 address check box for existing tasks or services

For Fargate tasks in a private subnet

Verify that your Fargate task has a default route (0.0.0.0/0) to either a NAT gateway, AWS PrivateLink, or another source of internet connectivity:

• If you use a NAT gateway, then place your NAT gateway in a public subnet. For more information, see Architecture with an internet gateway and a NAT gateway.
• If you use AWS PrivateLink, then confirm that your Fargate infrastructure can use security groups for your Amazon Virtual Private Cloud (Amazon VPC) endpoints.

Check your network access control list and security group settings

Verify that your network access control list (network ACL) and security groups don't block outbound access to port 443 from the subnet. For more information, see Control traffic to your AWS resources using security groups.

Note: Fargate tasks must have outbound access to port 443 to activate outgoing traffic and reach Amazon ECS endpoints.

Check your VPC endpoints

If you use AWS PrivateLink, then confirm that you have the required endpoints.

The following are the required endpoints for Fargate platform versions 1.3.0 or earlier:

• com.amazonaws.region.ecr.dkr
• S3 gateway endpoint

The following are the required endpoints for Fargate platform versions 1.4.0 or later:

• com.amazonaws.region.ecr.dkr
• com.amazonaws.region.ecr.api
• S3 gateway endpoint

Note: If your task definition uses AWS Secrets Manager, SSM parameters, or Amazon CloudWatch Logs, you might need to define endpoints. For more information, see Using an AWS Secrets Manager VPC endpoint and Using CloudWatch Logs with interface VPC endpoints.

For PrivateLink, confirm that the security groups for your VPC endpoints allow the Fargate infrastructure to use these security groups.

Check your IAM roles and permissions

The AWS Identity and Access Management (IAM) task execution role grants the ECS container and Fargate agents permission to make API calls on your behalf. Fargate requires this role for the following scenarios:

• You pull a container image from Amazon Elastic Container Registry (Amazon ECR)
• You use the awslogs log driver
• You use private registry authentication
• You use Secrets Manager secrets or Parameter Store, a capability of AWS Systems Manager, to reference sensitive data

If your use case involves any of the preceding scenarios, then confirm that you have the right permissions defined in your task execution role. For a complete list of required permissions, see Amazon ECS task execution IAM role.

Check for issues with pulling the image

When you pull an image, you might receive a cannotpullcontainer error for your Fargate task. If you receive this error, then complete the steps in How do I resolve the "cannotpullcontainererror" error for my Amazon ECS tasks on Fargate?

Configure your VPC in dual stack mode

For VPCs in dual-stack mode with Fargate, configure your VPC with an internet gateway or an outbound-only internet gateway to access the internet. You can configure these VPC only for tasks that are assigned an IPv6 address to access the internet. For more information, see Using a VPC in dual-stack mode.

Note: To troubleshoot your issue, you can also use Amazon ECS Exec to retrieve the logs from the container instance of your task or service.

Update your container dependency definition

A container dependency that's defined in the task definition can cause the Fargate task to be in the PENDING state indefinitely. Example: If container A depends on container Bs state, then container A is expected to stay in the PENDING state until container B reaches that state. If container B never reaches the desired state, then the task indefinitely stays in the PENDING state. To resolve this issue, evaluate your dependencies, and then update your dependencies if needed. For more information, see Container dependency.