How do I troubleshoot Amazon ECS tasks for Fargate that are stuck in the Pending state?
Last updated: 2021-04-05
My Amazon Elastic Container Service (Amazon ECS) task that's running on AWS Fargate is stuck in the PENDING state.
Check what routes to the internet your subnets are using
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 do 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 Modifying the public IPv4 addressing attribute for your subnet.
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're using a NAT gateway, place your NAT gateway in a public subnet. For more information, see Architecture with an internet gateway and a NAT gateway.
If you're using AWS PrivateLink, confirm that your Fargate inftrastructure is allowed to 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 Security groups for your VPC.
Note: Fargate tasks must have outbound access to port 443 to enable outgoing traffic and reach Amazon ECS endpoints.
Check your VPC endpoints
If you're using AWS PrivateLink, confirm that you have the required endpoints.
Required endpoints for Fargate platform versions 1.3.0 or earlier:
- S3 gateway endpoint
Required endpoints for Fargate platform versions 1.4.0 or later:
- S3 gateway endpoint
For more information, see Considerations for Amazon ECR VPC endpoints.
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 Secrets Manager with VPC Endpoints and Using CloudWatch Logs with Interface VPC Endpoints.
While using 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 task execution role grants the Amazon ECS container and Fargate agents permission to make AWS API calls on your behalf. This role is required by Fargate when you:
- Pull a container image from Amazon Elastic Container Registry (Amazon ECR)
- Use the awslogs log driver
- Use private registry authentication
- Reference sensitive data using Secrets Manager secrets or AWS Systems Manager Parameter Store parameters
If your use case involves any of the preceding scenarios, 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
If you receive a "cannotpullcontainer" error for your Fargate task, then complete the steps in How do I resolve the "cannotpullcontainererror" error for my Amazon ECS tasks on Fargate?
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.