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

Resolution

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

If you incorrectly configured your IAM role or trust relationship, then you might receive the following error:

"ECS was unable to assume the role 'arn:aws:iam::444455556666:role/Admin' 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."

To resolve, verify that your task role has the correct trust policy and confirm that you use the necessary IAM permissions for the IAM role.

Check your task role permissions

Make sure that your task definition includes the correct permissions for your IAM role. To check the permissions for your task role, complete the following steps:

1. Open the IAM console.
2. In the navigation pane, choose Roles.
3. Select your task role for your task definition.
4. Run the get-role AWS CLI command to review information about your task role:

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

   Note: Replace task-execution-role with the name of your IAM role for your task.

If you don't have a task role, then create a task IAM role.

Configure the trust policy for ecs-tasks.amazonaws.com

For the Amazon ECS task to assume the IAM role, configure the trust policy to allow the ecs-tasks.amazonaws.com service.

Complete the following steps:

1. Open the IAM console.

2. In the navigation pane, choose Roles.

3. Select your task role, and then choose Trust relationships.

4. Verify that the trust policy has ecs-tasks.amazonaws.com as the service.
   Example policy:

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

5. If you don't have ecs-tasks.amazonaws.com set as the service, then choose Edit trust policy.
   Update the policy with the example policy above and then choose Update policy.

6. In your task definition, specify the full IAM role ARN. For example, arn:aws:iam::444455556666:role/ecsTaskRole. For more information, see Updating an Amazon ECS task definition using the console.

7. Ensure that the IAM user or role that launches the Amazon ECS task has iam:PassRole permission.

Related information

Troubleshoot IAM roles

Amazon ECS task execution IAM role

Troubleshooting Amazon Elastic Container Service identity and access