Share Your AWS re:Post Experience - Quick 3 Question Survey
Help us improve AWS re:Post! We're interested in understanding how you use re:Post and its impact on your AWS journey. Please take a moment to complete our brief 3-question survey.
How do I troubleshoot common errors with API calls in Amazon ECS?
I want to troubleshoot common errors with API calls in Amazon Elastic Container Service (Amazon ECS).
Short description
An Amazon ECS API call might fail with one of the following errors:
- AccessDeniedException
- ClientException
- ClusterNotFoundException
- InvalidParameterException
- ServerException
- ServiceNotActiveException
- PlatformTaskDefinitionIncompatibilityException
- PlatformUnknownException
- ServiceNotFoundException
- UnsupportedFeatureException
You might also experience API issues with the application that's running inside your Amazon ECS tasks.
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.
When activity occurs in Amazon ECS, your API request is recorded in an AWS CloudTrail event in Event history, along with our AWS service events.
To view the CloudTrail event history and locate the API error, complete the following steps:
- Open the CloudTrail console.
- In the navigation pane, choose Event history.
- Choose the gear icon.
- Under Select visible columns, select Error code. Then, choose Confirm.
- On the Event history page, in Lookup attributes, select Event name.
- 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. - From the list of results, choose 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 your API call issues based on the error code that you receive:
AccessDeniedException
Your AWS Identity and Acess Management (IAM) user or role that makes the API call must have the required permissions. If the IAM user or role doesn't have the required permissions to perform the requested action, then you might get the following error:
"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: ecs:CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action"
In the CloudTrail event record, you can view the user information, event name, and error message:
Example user information:
"type": "AssumedRole","principalId": "AROAZEPPWYLQU45ZDJY6V:test-session", "arn": "arn:aws:sts::123456789012:assumed-role/test-role/test-session"
Example event name:
"eventName": "CreateCluster"
Example error message:
"errorMessage": "User: arn:aws:sts::123456789012:assumed-role/test-role/test-session is not authorized to perform: ecs:CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action"
To test a policy that isn't attached to a user, user group, or role, use the IAM policy simulator.
To resolve this error, add the appropriate permission to IAM identity's permission policy:
- Open the IAM console.
- In the navigation pane, choose Roles, User groups, or Users based on the IAM identity.
- Use the search filter to filter the role or user options. Then, select the IAM identity that you want to view.
- Choose the Permissions tab.
- To view the permissions that are associated with the IAM identity, expand the permissions policy.
- 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).
ClientException
You receive ClientException errors when the ECS client specifies an identifier or resource that isn't valid or doesn't exist. For example, you refer to an incorrect task definition when you use RunTask or StartTask, and you get one of the following error messages:
"An error occurred (ClientException) when calling the RunTask operation: TaskDefinition not found."
"An error occurred (ClientException) when calling the StartTask operation: TaskDefinition not found."
To prevent this issue, update the referenced resources in the command, API calls, and your code to valid values.
ClusterNotFoundException
If Amazon ECS can't find the specified cluster during the operation, then you might get the following error message:
"An error occurred (ClusterNotFoundException) when calling the StartTask operation: Cluster not found."
To resolve this issue, update the cluster name to the correct value that you run in the command, API calls, or your code.
To list the existing ECS clusters, run the list-clusters command:
$ aws ecs list-clusters --region example-region{ "clusterArns": [ "arn:aws:ecs:ap-southeast-2:123456789012:cluster/my-cluster", "arn:aws:ecs:ap-southeast-2:123456789012:cluster/my-private-cluster" ] }
Then, verify that the cluster that's mentioned in the API call exists.
InvalidParameterException
The InvalidParameterException error occurs when the parameter that you included in the command isn't valid and the version of the task definition doesn't exist.
Example command with a parameter that isn't valid and no task definition version:
$ aws ecs run-task --task-definition CentOS:3 --cluster example-cluster --region ap-southeast-2
Because the task definition doesn't exist, you get an error similar to the following:
"An error occurred (InvalidParameterException) when calling the RunTask operation: TaskDefinition not found."
To resolve this error, update the parameters in the command to valid values.
ServerException
The ServerException error occurs when a server error relates to the API call. An HTTP 500 status code response usually occurs when there's an internal server error with the ECS service in the service's AWS Region. This error is usually temporary. To resolve the issue, wait some time and then try to make the API call again. If the issue still persists, then contact AWS Support.
ServiceNotActiveException
The ServiceNotActiveException error occurs when an updating ECS service is inactive. Verify that the ECS service that's updating is in the ECS cluster and is in the ACTIVE state.
To list all the services in the cluster, run the list-clusters command:
$ aws ecs list-services --cluster example-cluster
Verify that the service that's updating is listed in the command's output. To verify that the service is in the ACTIVE state, run the describe-services command:
$ aws ecs describe-services --services example-service-name --cluster example-cluster
The output looks similar to the following:
{ "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", ...... }] }
PlatformTaskDefinitionIncompatibilityException
When you launch a task on a platform that doesn't meet the required capabilities in the task definition, you get the PlatformTaskDefinitionIncompatibilityException error. In the following example, a service is created 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 Test-fargate-EFS \ --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
Because the platform version doesn't support the requirements, you get the following error message:
"An error occurred (PlatformTaskDefinitionIncompatibilityException) when calling the CreateService operation: One or more of the requested capabilities are not supported."
To resolve this issue, update the platform version to one that supports the required capabilities in the task definition. For more information, see AWS Fargate platform versions.
PlatformUnknownException
If you specify an unknown or incorrect platform version when you launch a task, then you might get the following error message:
"An error occurred (PlatformUnknownException) when calling the CreateService operation: The specified platform does not exist."
In the following example, the incorrect platform version 1.3 is provided instead of version 1.3.0:
$ aws ecs create-service \ --cluster example-cluster\ --task-definition example-task \ --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
To resolve this issue, update the platform version to the correct version. 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 confirm that the service is in the cluster. To view all the services in the cluster, run the list-clusters command:
$ aws ecs list-services --cluster example-cluster
UnsupportedFeatureException
The UnsupportedFeatureException error occurs when an ECS feature isn't available in a specific Region. For example, you try to launch a Fargate task in a newly launched Region where Fargate isn't available yet. To resolve this issue, run the API in a Region that supports the feature.
Application API issues
When you access the application that's hosted inside an ECS task, you might get the following common HTTP 5## status code responses:
HTTP 500 - Internal server error: When the application encounters an unexpected condition, you get this error. This error might occur because of an application misconfiguration or an error with the application.
HTTP 503 - Service unavailable: When the ECS task experiences heavy workload and can't service the request, you might get this error. Or, the application that's running inside your task is down for maintenance.
To troubleshoot these issues, review the application logs for the ECS tasks in Amazon CloudWatch Logs. Each task definition is associated with a log stream that contains the application log from the task.
To view information about the log group and log stream for your task definition, run the describe-task-definition command:
$ aws ecs describe-task-definition —task-definition example-taskdefinition
The output looks similar to the following:
... "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "/ecs/example-task", "awslogs-region": "ap-southeast-2", "awslogs-stream-prefix": "ecs" } } ...
Related information

Relevant content
- asked 10 months agolg...
- Accepted Answerasked a year agolg...
- asked 8 months agolg...
- AWS OFFICIALUpdated a year ago
- AWS OFFICIALUpdated a year ago
- AWS OFFICIALUpdated a year ago
- AWS OFFICIALUpdated a year ago