How do I troubleshoot the CloudFormation error "The role defined for the function cannot be assumed by Lambda"?

Short description

Sometimes the AWS Lambda function fails to accept the IAM role defined for it on CloudFormation.

Resolution

Verify if the correct IAM role ARN is passed to the Lambda function

If the IAM role's Amazon Resource Name (ARN) for the function already exist in the account, then make sure that it has the correct syntax. For instance:

• Check that the role name is spelled correctly and follows the case-sensitive requirement.
• Make sure that the IAM_ROLE_NAME exactly matches the existing IAM_ROLE_NAME in the account. For example:

  Role: !Sub arn:${AWS::Partition}:iam::${AWS::AccountId}:role/IAM_ROLE_NAME

Troubleshoot the IAM role and its associated policy

Review the IAM policy defined for the Lambda function's assumed role. Verify that the IAM role has all the necessary permissions. Make sure that the Principal section of the policy is correctly configured as shown below:

LambdaExecutionRole:    
  Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
        - Effect: Allow
          Principal:
            Service:
            - lambda.amazonaws.com
          Action:
          - sts:AssumeRole

Resolve the dependency between the IAM role and the Lambda function

If the IAM role and the Lambda function are created in different stacks, then create the role first. If the Lambda function in the stack initiates first, then the stack might fail with this error.

It's a best practice to create the IAM role in the same stack as the Lambda function. Use intrinsic functions, such as GetAtt and !Ref, to pass the IAM role to the Lambda function.