How do I troubleshoot an Amazon ECS RunTask API for a Fargate task that fails with a "Capacity is unavailable" error?
I want to use the Amazon Elastic Container Service (Amazon ECS) RunTask API to launch an AWS Fargate task. However, the task fails because of unavailable capacity.
Short description
If Amazon ECS doesn't have the capacity to launch a Fargate task, then the RunTask API fails with the following error message:
"Capacity is unavailable at this time. Please try again later or in a different availability zone"
To troubleshoot this error, wait before you retry the RunTask API. You can also use AWS Step Functions to automate the retry process.
Resolution
Retry the RunTask API at a later time.
The following practices might grant you more available capacity for RunTask and shorten your wait time:
- Because Amazon ECS manages capacity by Availability Zone, it's a best practice to set multiple subnets in different Availability Zones in the networkConfiguration.awsvpcConfiguration.subnets RunTask request parameter.
- Set the overrides.cpu and overrides.memory RunTask request parameters to different CPU and memory combinations. For more information, see Task CPU and memory.
Automate the RunTask API
To automate the initiation and subsequent retries of the RunTask API, use Step Functions.
If you start RunTask from Step Functions and the task fails because of limited capacity, then Step Functions records an ECS.AmazonECSException in its ErrorEquals field. You can use this information to configure future retries.
To set up a Step Function workflow, see Manage Amazon ECS or Fargate Tasks with Step Functions. For more information on Step Functions error reporting, see Error handling in Step Functions.
If you regularly call the RunTask API from Amazon EventBridge, then call Step Functions from EventBridge to automate your retries.
-
Check Fargate Cluster Capacity:
- Verify sufficient resources in the Fargate cluster.
-
Check Task Definition Resources:
- Ensure task resource requirements are within cluster limits.
-
Check Service Quotas:
- Confirm Fargate resource quotas are not exceeded.
-
Review Task Placement Constraints:
- Ensure placement constraints allow task placement.
-
Check VPC and Subnet Configuration:
- Verify correct VPC and subnet settings.
-
Update ECS Agent:
- Ensure ECS agent on Fargate instances is up to date.
-
Check for Service Events:
- Review ECS service events for additional details.
-
Check CloudWatch Logs:
- Examine CloudWatch Logs for error messages.
-
Review IAM Roles and Policies:
- Confirm IAM roles have necessary permissions.
-
Contact AWS Support:
- If issues persist, seek assistance from AWS Support.
Thank you for your comment. We'll review and update the Knowledge Center article as needed.
Relevant content
- asked a year ago
- AWS OFFICIALUpdated 2 months ago
- AWS OFFICIALUpdated 3 months ago
- AWS OFFICIALUpdated 7 months ago
