cfn-error-detector is a command-line tool that helps detect the root cause of AWS CloudFormation deployment failures. It can identify resources in error even within complex nested stacks, making troubleshooting easier and more efficient.

First, install Rye by following the official installation guide.

Once Rye is installed, you can install cfn-error-detector using the following command:

rye tools install --git 'https://github.com/techscore/cfn-error-detector' cfn_error_detector

This will install the cfn-error-detector command-line tool.

If the stack name is foo-app-stack...

To show the cause of error for a specified stack, use the detect subcommand followed by the stack name. For example:

cfn-error-detector detect foo-app-stack

To display the path of the template file that caused the error, specify the root template file path.

cfn-error-detector detect foo-app-stack -t template.yaml

To manually initiate a stack rollback, use the rollback subcommand followed by the stack name:

cfn-error-detector rollback foo-app-stack

It's recommended to disable automatic rollback for CloudFormation stacks. When a stack rollback occurs, child stacks are deleted, which may cause failures in retrieving events (cloudformation:DescribeStackEvents). By disabling automatic rollback, you can better investigate the root cause of failures.

To use cfn-error-detector, ensure your AWS IAM user or role has the following permissions:

• cloudformation:DescribeStackResources
• cloudformation:DescribeStacks
• cloudformation:DescribeStackEvents
• cloudformation:RollbackStack

Contributions to cfn-error-detector are welcome! Please refer to the project's GitHub repository for guidelines on how to contribute.

For issues, feature requests, or questions, please open an issue on the GitHub repository.