API failure reasons - Amazon Elastic Container Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

API failure reasons

When an API action that you have triggered through the Amazon ECS API, console, or the Amazon CLI exits with a failures error message, the following may assist in troubleshooting the cause. The failure will return a reason and the Amazon Resource Name (ARN) of the resource associated with the failure.

Many resources are Region-specific, so when using the console ensure that you set the correct Region for your resources. When using the Amazon CLI, make sure that your Amazon CLI commands are being sent to the correct Region with the --region region parameter.

For more information about the structure of the Failure data type, see Failure in the Amazon Elastic Container Service API Reference.

The following are examples of failure messages you might receive when running API commands.

API action

Failure reason




The specified cluster wasn't found. Verify the spelling of the cluster name.



The specified container instance wasn't found. Verify that you specified the cluster the container instance is registered to and that both the container instance ARN or ID is correct.



The specified service wasn't found. Verify that the correct cluster or Region is specified and that the service ARN or name is valid.



The specified task wasn't found. Verify the correct cluster or Region is specified and that both the task ARN or ID is valid.

RunTask or StartTask


The resource or resources that are requested by the task are unavailable on the container instances in the cluster. If the resource is CPU, memory, ports, or elastic network interfaces, you might need to add additional container instances to your cluster.

For RESOURCE:ENI errors, your cluster doesn't have any available elastic network interface attachment points, which are required for tasks that use the awsvpc network mode. Amazon EC2 instances have a limit to the number of network interfaces that can be attached to them, and the primary network interface counts as one. For more information about how many network interfaces are supported for each instance type, see IP Addresses Per Network Interface Per Instance Type in the Amazon EC2 User Guide for Linux Instances.

For RESOURCE:GPU errors, the number of GPUs requested by the task are unavailable and you might need to add GPU-enabled container instances to your cluster. For more information, see Working with GPUs on Amazon ECS.


The container instance that you attempted to launch a task onto has an agent that's currently disconnected. To prevent extended wait times for task placement, the request was rejected.

For information about how to troubleshoot an agent that's disconnected, see How do I troubleshoot a disconnected Amazon ECS agent.


The container instance that you attempted to launch a task onto is in a different Availability Zone than the subnets that you specified in your awsVpcConfiguration.


Your task definition contains a parameter that requires a specific container instance attribute that isn't available on your container instances. For example, if your task uses the awsvpc network mode, but there are no instances in your specified subnets with the ecs.capability.task-eni attribute. For more information about which attributes are required for specific task definition parameters and agent configuration variables, see Task definition parameters and Amazon ECS container agent configuration.



The container instance you attempted to launch the task onto can't be found. Perhaps the wrong cluster or Region is specified, or the container instance ARN or ID is misspelled.


The container instance that you attempted to launch a task onto was previously deregistered with Amazon ECS and can't be used.