feat(cli): improve deployment failure reporting using CloudFormation `FailedEvents` filter

[garysassano]

Describe the feature

CloudFormation recently released a new feature for the DescribeEvents API that allows filtering events by root cause (FailedEvents=true) and grouping them by OperationId.

Currently, when a CDK deployment fails, the CLI outputs a large number of events, making it difficult to visually scan for the actual error that caused the rollback.

The new API capability is described here:
Accelerate infrastructure development with CloudFormation pre-deployment validation and simplified troubleshooting

Use Case

When deploying stacks with cdk deploy, you may encounter deployment failures. Finding the root cause currently requires scrolling through a long history of UPDATE_IN_PROGRESS and UPDATE_COMPLETE events to find the one CREATE_FAILED or UPDATE_FAILED event that triggered the rollback.

If the CLI utilized the new FailedEvents=true filter, it could immediately present the specific error(s) at the bottom of the log output, significantly reducing the time required to debug deployment issues.

Proposed Solution

No response

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

CDK version used

2.223.0

Environment details (OS name and version, etc.)

Ubuntu 24.04

[pahud]

Hi @garysassano,

Thanks for this feature request! The new CloudFormation FailedEvents filter is a good capability that could significantly improve the debugging experience when deployments fail.

Currently, the CDK CLI's StackEventPoller retrieves all stack events without filtering, which can make it challenging to identify the root cause when scrolling through numerous IN_PROGRESS and COMPLETE events.

This seems like a valuable enhancement that would align well with CloudFormation's recent improvements.

One consideration would be determining the best UX approach - whether to always use the filter, make it configurable, or use it only in specific scenarios (like post-failure summaries). I'd be curious to hear your thoughts on the preferred behavior.

Making this a p2 and we welcome upvotes 👍

[garysassano]

Example of a failure without explicit reason:

If you don’t want to see a notice anymore, use "cdk acknowledge <id>". For example, "cdk acknowledge 34892".
❌  cdk-aws-ecs-managed-instance-dev failed: ToolkitError: Failed to create ChangeSet cdk-deploy-change-set on cdk-aws-ecs-managed-instance-dev: FAILED, The following hook(s)/validation failed: [AWS::EarlyValidation::ResourceExistenceCheck]. To troubleshoot Early Validation errors, use the DescribeEvents API for detailed failure information.
👾 Task "deploy" failed when executing "cdk deploy" (cwd: /home/user/github/cdk-aws-ecs-managed-instance)