How do I troubleshoot the error “ECS was unable to assume the role” when running the Amazon ECS tasks?

Last updated: 2022-03-04

I'm getting the following error when I run my Amazon Elastic Container Service (Amazon ECS)/AWS Fargate tasks:

ECS was unable to assume the role 'arn:aws:iam::xxxxxxxxxxxx:role/yyyyyyyy' that was provided for this task. Please verify that the role being passed has the proper trust relationship and permissions and that your IAM user has permissions to pass this role.

Resolution

You get this error because of one or more of the following reasons:

  • The task execution AWS Identity and Access Management (IAM) role or task role specified in the task definition doesn't exist.
  • The task execution IAM role or task role specified in the task definition doesn't have the correct trusted relationship policy.

Verify that the task execution role or task role exists

To check if the task execution role or task role defined in the task definition exists using the console, do the following:

  1. Open the IAM console.
  2. Choose Roles.
  3. Search the list of roles for the task execution role or task role that you included in the task definition.

To check if the task execution role or task role exists using AWS Command Line Interface (AWS CLI), run the following command:

Note: This command retrieves information about the specified IAM role.

aws iam get-role --role-name example-task-execution-role

Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent version of the AWS CLI.

If the role doesn't exist, then you get the following error:

An error occurred (NoSuchEntity) when calling the GetRole operation: The role with name example-task-execution-role cannot be found.

If the role doesn't exist, consider doing either of the following:

Verify if the task execution role or task role in the task definition has the correct trusted relationship policy

Be sure that the trusted relationship policy for the role allows the service ecs-tasks.amazonaws.com. This is required for the Amazon ECS task to assume the specified IAM role.

To check the trust relationship policy and update as needed, do the following:

1.    Open the IAM console.

2.    In the navigation pane, choose Roles.

3.    Search the list of roles for the task execution role or task role that you included in your task definition.

4.    Choose the role.

5.    Choose Trust relationships.

6.    Verify if the trust relationship for the role contains the following policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "ecs-tasks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

7.    If the trust relationship matches the policy, choose Cancel. Otherwise, choose Edit trust relationship.

8.    Copy the preceding policy into the Policy Document window, and then choose Update Trust Policy.