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

3 minute read
1

When I run my Amazon Elastic Container Service (Amazon ECS) or AWS Fargate tasks, I get an “ECS was unable to assume the role” error.

Short description

When you run Amazon ECS or Fargate tasks, you might get the following error:

"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."

This error can occur for one of the following reasons:

  • The task execution AWS Identity and Access Management (IAM) role or task role that's specified in the task definition doesn't exist.
  • The trust relationship isn't established in the trust policy for the task execution IAM role or task role that's specified in the task definition.

Resolution

Update the task definition or create an IAM role

First, confirm whether the IAM role or task role exists.

Complete the following steps:

  1. Open the IAM console.
  2. In the navigation pane, choose Roles.
  3. Search the list of roles for the task IAM role or task role that you included in the task definition.

To use the AWS Command Line Interface (AWS CLI) , run the get-role command:

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

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

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."

To resolve this issue, complete one of the following tasks:

Allow ecs-tasks.amazonaws.com in the trust policy

For the ECS task to assume the IAM role, the trust policy for the role must allow the ecs-tasks.amazonaws.com service. First, check whether the trust policy allows ecs-tasks.amazonaws.com. If it doesn't, then edit the policy to allow the service.

Complete the following steps:

  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, and then select the role.

  4. Choose Trust relationships.

  5. Check whether the trust policy allows ecs-tasks.amazonaws.com:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "",
          "Effect": "Allow",
          "Principal": {
            "Service": "ecs-tasks.amazonaws.com"
          },
          "Action": "sts:AssumeRole"
        }
      ]
    }
  6. If the policy allows ecs-tasks.amazonaws.com, then choose Cancel. Otherwise, choose Edit trust policy.

  7. Edit the trust policy to allow ecs-tasks.amazonaws.com, and then choose Update policy.

Related information

Amazon ECS task IAM role

Amazon ECS task execution IAM role

Troubleshooting Amazon Elastic Container Service identity and access

AWS OFFICIAL
AWS OFFICIALUpdated 9 days ago