How do I troubleshoot errors caused by CloudFormation macros ?

Resolution

You might see the following common errors when you use custom macros in your CloudFormation stack:

Error: "Received malformed response from transform <ACCOUNT>:<Macro-Name."

This error message appears in the CloudFormation stack event or on the change set.

Typically, CloudFormation expects the underlying AWS Lambda function that runs the macro to return a response in the following JSON format:

{
 "requestId" : "$REQUEST_ID",
 "status" : "$STATUS", 
 "fragment" : { ... }
 "errorMessage": "optional error message for failures"
}

The error occurs when the CloudFormation template fails to accept the value or response it receives from the AWS Lambda function.

To troubleshoot this error, review your Amazon CloudWatch Logs for the underlying Lambda function that has the macro that triggered the response.

Follow these steps to resolve the error:

1. Log in to the CloudFormation console.
2. Select the stack that failed to create or update.
3. Select the Template tab of that stack.
4. Find the name of the macro in the template. The name is referenced in the Transform section of the template. Or, find the name in the Fn::Transform function.
5. Find the stack that deployed that macro resource. Check AWS::CloudFormation::Macro.
   Note: The name of the macro resource is its physical ID. Check the resource deployed by a stack and its physical ID by selecting the Resources tab for each stack.
6. Choose the Template tab of that stack. Then, find the Lambda function name in the FunctionName property of the AWS::CloudFormation::Macro resource in the stack template.
7. Navigate to the Lambda console. Choose the function name that you found earlier.
8. Choose Monitor. Then, select, View logs in CloudWatch.
9. Check the latest CloudWatch Logs stream for any error messages.
   -or-
   Check whether the final response sent by the Lambda function is in the correct JSON format as shown earlier.

Error: "Failed to execute transform <ACCOUNT>:<Macro-Name>"

This error indicates that the AWS Identity and Access Management (IAM) user, role, or the service role didn't invoke the Lambda function. The error occurred because the IAM entity didn't have the necessary permissions.

AWS CloudFormation successfully runs a macro included in the template if the user has the lambda:InvokeFunction permissions for the underlying Lambda function. The permission must be present on the IAM identity that performs the stack operations. For more information on Lambda function-related permission errors, see How do I troubleshoot Lambda function failures?

Error: "No transform named <ACCOUNT>:<Macro-Name> found."

This error indicates that the macro in the Transform section of the template or in the Fn::Transform function doesn't exist in the account and Region where the stack's deployed. Check the name of the macro that's referenced in the account and Region. Then, use the same name to reference the macro in the CloudFormation template.

Related information

AWS CloudFormation macro function interface

Considerations when creating AWS CloudFormation macro definitions

AWS CloudFormation macro account scope and permissions