How do I troubleshoot common errors with API calls in Amazon ECS?

Short description

The following errors can cause an Amazon ECS API call to fail:

• "AccessDeniedException"
• "ClientException"
• "ClusterNotFoundException"
• "InvalidParameterException"
• "ServerException"
• "ServiceNotActiveException"
• "PlatformTaskDefinitionIncompatibilityException"
• "PlatformUnknownException"
• "ServiceNotFoundException"
• "UnsupportedFeatureException"

Applications that run inside your Amazon ECS tasks can also cause your Amazon ECS API call to fail.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Locate an API call error

When activity occurs in Amazon ECS, AWS CloudTrail records your API request as an event in Event history.

To view your AWS CloudTrail event history and locate the API error, complete the following steps:

1. Open the CloudTrail console.
2. In the navigation pane, choose Event history.
3. Choose the gear icon.
4. Under Select visible columns, choose Error code. Then, choose Confirm.
5. On the Event history page, in Lookup attributes, choose Event name.
6. For Enter an event name, enter the action that failed.
   Note: If you don't know the event name, then go to the Event history page. In Lookup attributes, choose Event source. For Enter an event source, select ecs.amazonaws.com to filter all events related to your ECS service.
7. From the list of results, select the events with error codes that you want to know more about.

Note: You can also use Amazon Athena to query CloudTrail logs for events by errorcode.

Resolve an API call error

Take the following actions based on the error code that you received.

AccessDeniedException

If your AWS Identity and Access Management (IAM) user or role doesn't have the required permissions, then you receive an "AccessDeniedException" error. The following error example indicates that user arn:aws:sts::123456789012:assumed-role/test-role/test-session doesn't have the necessary permissions to perform the CreateCluster action:

"An error occurred (AccessDeniedException) when calling the CreateCluster operation: User: arn:aws:sts::123456789012:assumed-role/test-role/test-session is not authorized to perform: CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action"

To add the appropriate permission to IAM identity's permission policy, complete the following steps:

1. Open the IAM console.
2. In the navigation pane, choose Roles, User groups, or Users based on the IAM identity.
3. Use the search filter to filter the role or user options. Then, select the IAM identity that you want to view.
4. Choose the Permissions tab.
5. To view the permissions that are associated with the IAM identity, expand the permissions policy.
6. In the permissions policy, add ecs:your-event-name to the Actions list. Then, select Allow for Effect. Or, create a new policy that allows ecs:your-event-name, and attach the policy to the IAM role or user. For more information, see Editing customer managed policies (console).

You can use the IAM policy simulator to test a policy that isn't attached to an IAM user, user group, or role.

ClientException

If your ECS client specifies an identifier or resource that isn't valid or doesn't exist, then you receive a "ClientException" error. The following error example indicates that the RunTask command refers to a TaskDefinition that isn't valid:

"An error occurred (ClientException) when calling the RunTask operation: TaskDefinition not found."

Verify that you reference the correct resources in the command, the API calls, and your code.

ClusterNotFoundException

If Amazon ECS can't find the cluster that you specified for an operation, then you receive a "ClusterNotFoundException" error. The following error example indicates that Amazon ECS can't find the cluster that you specified for the StartTask operation:

"An error occurred (ClusterNotFoundException) when calling the StartTask operation: Cluster not found."

Verify that you reference the correct cluster name in the command, API calls, and your code.

To list all your current ECS clusters, run the list-clusters AWS CLI command:

aws ecs list-clusters --region example_region

Note: Replace example_region with your AWS Region.

Then, verify that the cluster that you reference in the API call exists.

InvalidParameterException

If a parameter that you enter in a command isn't valid, and the version of the task definition doesn't exist, then you receive the following error:

"An error occurred (InvalidParameterException) when calling the RunTask operation: TaskDefinition not found."

The following example RunTask command includes that the CentOS:3 task definition doesn't exist:

aws ecs run-task --task-definition CentOS:3 --cluster example_cluster --region ap-southeast-2

Note: In the preceding example, replace example_cluster with the name of your cluster.

The following error example corresponds with the previous RunTask command:

"An error occurred (InvalidParameterException) when calling the RunTask operation: TaskDefinition not found."

Verify that the parameters in your command are valid.

ServerException

If a sever is down when you make an API call, then you receive a "ServerException" error. If you receive this error for all API calls, then the AWS service is unavailable.

ServerException errors are often temporary. Wait, and then make the API call again. If the issue persists, then contact AWS Support and provide the following information:

• Provide the timestamp that corresponds to the error.
• If you use the command line, then provide the command that returns the error.
• If you use a programming language or infrastructure as code tools that use AWS SDK, then provide the code block that returns the error.
• If you use the AWS Management Console, then provide the URL of the AWS Management Console page and the action that returns the error.

ServiceNotActiveException

If you update an Amazon ECS service that's inactive, then you receive a "ServiceNotActiveException" error. Verify that the ECS service that you want to update is in your ECS cluster and is in the ACTIVE state.

To list all the services in a cluster, run the list-clusters AWS CLI command:

aws ecs list-services --cluster example_cluster

Note: Replace example_cluster with the name of your cluster.

Verify that the command's output contains the service that you want to update. Then, run the describe-services command to verify that the service is in the ACTIVE state:

aws ecs describe-services --services example_service_name --cluster example_cluster

Note: Replace example_service_name and example_cluster with your values.

The following output example indicates that the example-service is in the ACTIVE state:

{    "services": [{  
        "serviceArn": "arn:aws:ecs:ap-southeast-2:111122223333:service/my-cluster/example-service",  
        "serviceName": "example-service",  
        "clusterArn": "arn:aws:ecs:ap-southeast-2:111122223333:cluster/example-cluster",  
        "loadBalancers": [],  
        "serviceRegistries": [],  
        "status": "ACTIVE",  
        ......  
    }]  
}

If your service isn't in the ACTIVE state, then verify that your Amazon ECS service's Number of tasks value is greater than zero. You can also run the update-service AWS CLI command to update your Number of tasks value to 1:

aws ecs update-service --cluster example_cluster_name --service example_service_name --desired-count 1

Note: Replace example_cluster_name and example_service_name with your values. You can set the desired count value to a number greater than zero.

Then, in the ECS Console, verify that your task definition state is ACTIVE. you can also run the describe-task-definition command:

aws ecs describe-task-definition --task-definition example_taskdefinition

Note: Replace example_taskdefinition with your task defintion.

Check your CloudWatch logs for service failures or network reviews that correspond with your ServiceNotActiveException error.

PlatformTaskDefinitionIncompatibilityException

If you launch a task on a platform that doesn't meet the task definition's required capabilities, then you receive a "PlatformTaskDefinitionIncompatibilityException" error. In the following example error, platform version 1.3.0 doesn't support the create-service AWS CLI command's requirements:

"An error occurred (PlatformTaskDefinitionIncompatibilityException) when calling the CreateService operation: One or more of the requested capabilities are not supported."

The following example create-service command creates a service with an Amazon Elastic File System (Amazon EFS) volume that's attached on platform version 1.3.0:

aws ecs create-service \  
    --cluster example_cluster \  
    --task-definition  example_taskdefinition  \  
    --launch-type FARGATE \  
    --service-name example_service \  
    --desired-count 1 \  
    --network-configuration "awsvpcConfiguration={subnets=[subnet-ed7d31b5,subnet-833ef1cb],securityGroups=[sg-eeb28aa1]}" \  
    --platform-version 1.3.0

Verify that your AWS Fargate platform version supports the capabilities that your task definition requires.

PlatformUnknownException

If you specify an unknown or incorrect platform version when you launch a task, then you receive a "PlatformUnknownException" error. The following error example indicates that platform version that you specify in a create service operation isn't correct:

"An error occurred (PlatformUnknownException) when calling the CreateService operation: The specified platform does not exist."

The following create-service command example contains the incorrect platform version 1.3, instead of the correct version 1.3.0:

aws ecs create-service \    --cluster example_cluster\  
    --task-definition example_taskdefinition \  
    --launch-type FARGATE\  
    --enable-execute-command \  
    --service-name example_service\  
    --desired-count 1 \  
    --network-configuration="awsvpcConfiguration={subnets=["subnet-ed7d31b5","subnet-833ef1cb"],securityGroups=["sg-eeb28aa1"]}"\  
    --platform-version 1.3

Verify that the platform version that you specify when you launch a task is correct. For more information, see Fargate Linux platform versions for Amazon ECS and Fargate Windows platform versions for Amazon ECS.

ServiceNotFoundException

The "ServiceNotFoundException" error occurs when the specified ECS service doesn't exist in your command or code. Verify that the service name in your command or code is correct, and then confirm that the service is in the cluster. To view all the services in the cluster, run the list-clusters AWS CLI command:

aws ecs list-services --cluster example_cluster

Note: Replace example_cluster with your cluster.

UnsupportedFeatureException

The "UnsupportedFeatureException" error occurs when you launch a Fargate task in an AWS Region where Fargate doesn't support your container. For more information, see Supported Regions for Amazon ECS on AWS Fargate.

Troubleshoot API issues in applications

You can receive the following common HTTP 5## status code responses when you access the application that's hosted inside an ECS task:

• An "HTTP 500 - Internal server" error occurs if an application encounters an unexpected condition, such as an error. Or, if you misconfigure an application, then you receive this error.
• An "HTTP 503 - Service unavailable" error occurs if an ECS task experiences heavy workload. Or, if the application inside your task is down for maintenance, then you receive this error.

Review the application logs for your ECS tasks in Amazon CloudWatch Logs. Each task definition corresponds with a log stream that contains the application log from the task. To view information about your task definition's log group and log stream, run the describe-task-definition command:

aws ecs describe-task-definition --task-definition example_taskdefinition

Note: Replace example_task_definition with your task definition.

Related information

Amazon ECS API failure reasons