How do I resolve the "Role [role_arn] is invalid or cannot be assumed" error when I update or delete a CloudFormation stack?

Resolution

CloudFormation uses an AWS Identity and Access Management (IAM) role to make calls to resources in a stack on your behalf. If there's an issue with this IAM role, then you receive the "Role [role_arn] is invalid" error.

To resolve this issue, take the following actions:

Confirm that the IAM role exists

Complete the following steps:

1. Open the IAM console.
2. In the navigation pane, choose Roles.
3. Under Role name, select the IAM role mentioned in the error message.
4. If the role exists, then either confirm that the role trust policy allows CloudFormation to assume the IAM role, or override the current IAM role. If the role doesn't exist, then create a new IAM role.

Create a new IAM role

Complete the following steps:

1. Create a new IAM role with the same name as the role mentioned in the error.
2. Verify that the new IAM role has the required permissions for CloudFormation to create, update, or delete resources in your stack. CloudFormation doesn't have predefined policies for resource-based permissions. It's a best practice to use your CloudFormation template to configure permissions that use the principle of least privilege. For example policies, see CloudFormation actions.
   Note: If the new role doesn't have the required IAM permissions, then the stack operations might fail. For example, to delete an Amazon Elastic Compute Cloud (Amazon EC2) instance resource, the IAM role must have the permission for the ec2:TerminateInstances action. If the role doesn't have that permission, then the delete operation fails.

Confirm that the role trust policy allows CloudFormation to assume the IAM role

Complete the following steps:

1. Open the IAM console.

2. In the navigation pane, choose Roles.

3. Under Role name, choose the IAM role mentioned in the error message.

4. Choose the Trust relationships tab.

5. Verify that the trust relationship shows cloudformation.amazonaws.com as a trusted entity.
   If cloudformation.amazonaws.com isn't listed as a trusted entity, then choose Edit trust relationship.

6. In the Policy Document editor, enter the following CloudFormation service role trust policy:

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

7. Choose Update Trust Policy.

Override the current IAM role that CloudFormation uses

Complete the following steps:

1. To update the stack, run the following update-stack command:

   aws cloudformation update-stack --stack-name my-stack --template-body file://my-stack-template.json --role-arn arn:aws:iam::123456789123:role/cloudformation-role

   Note: Replace my-stack with your stack name, my-stack-template.json with your template, and 123456789123 with your IAM role ARN.
2. To delete the stack, run the following delete-stack command:

   aws cloudformation delete-stack --stack-name my-stack --role-arn arn:aws:iam::123456789123:role/cloudformation-role

   Note: Replace my-stack with your stack name, and 123456789123 with your IAM role ARN.

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.

Related information

AWS CloudFormation service role