feat: `cdk diagnose` displays the root cause of a past stack deployment failure by rix0rrr · Pull Request #1378 · aws/aws-cdk-cli

rix0rrr · 2026-04-16T14:57:40Z

Useful when you use a CI/CD system to deploy stacks, but the failure reason is hard to parse.

This PR unifies and makes the error analysis and printing paths of cdk deploy accessible as a separate subcommand, cdk diagnose. This allows you to get the same interpretation of CloudFormation error reporting strategies, as well as source localization for a CI/CD deployment as is possible today for a deployment performed directly via the CLI.

In the future, we will further extend the diagnosis that the CLI performs to get you more information.

This is what errors look like now (both for cdk deploy and cdk diagnose):

    ❌ Stack cdktest-0648snacfpxl-diagnose-deploy-fail:
    Early validation failed for change set cdk-deploy-change-set:
     └─ cdktest-0648snacfpxl-diagnose-deploy-fail
         └─ BadPolicy  (AWS::IAM::Policy BadPolicy)
            🛑 Required property [PolicyName] not found (at /Resources/BadPolicy/Properties)
            Source Location: new DeployFailStack (/private/var/folders/w3/3m2f73xn1rq69wbbx9zw70s00000gq/T/cdk-integ-0648snacfpxl/app.js:29:5)
                             Object.<anonymous> (/private/var/folders/w3/3m2f73xn1rq69wbbx9zw70s00000gq/T/cdk-integ-0648snacfpxl/app.js:69:1)
                             Module._compile (node:internal/modules/cjs/loader:1761:14)
                             Module._extensions..js (node:internal/modules/cjs/loader:1893:10)
                             Module.load (node:internal/modules/cjs/loader:1481:32)
                             Module._load (node:internal/modules/cjs/loader:1300:12)
                             TracingChannel.traceSync (node:diagnostics_channel:328:14)
                             wrapModuleLoad (node:internal/modules/cjs/loader:245:24)
                             Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
                             node:internal/main/run_main_module:33:47

Broad design of this code:

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

…nt failure Useful when you use a CI/CD system to deploy stacks, but the failure reason is hard to parse. This PR unifies makes the error analysis and printing paths of `cdk deploy` accessible as a separate subcommand, `cdk diagnose`. This allows you to get the same interpretation of CloudFormation error reporting strategies, as well as source localization for a CI/CD deployment as is possible today for a deployment performed directly via the CLI. In the future, we will further extend the diagnosis that the CLI performs to get you more information. This PR extends the bootstrap template permissions with `List` permissions for the `ChangeSets`, turns them into `List*` and `Describe*` so that if there are future read-only operations we don't have to keep adding them. It also turns on `IncludeNestedStack: true` for CreateChangeSet so that early validation is run for nested stacks.

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

codecov-commenter · 2026-04-22T14:12:02Z

Codecov Report

❌ Patch coverage is 49.05660% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.93%. Comparing base (2ee00f1) to head (53ff33b).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/aws-cdk/lib/cli/cli.ts	10.52%	17 Missing ⚠️
packages/aws-cdk/lib/cli/cdk-toolkit.ts	61.11%	7 Missing ⚠️
packages/aws-cdk/lib/cxapp/exec.ts	25.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1378      +/-   ##
==========================================
- Coverage   88.14%   87.93%   -0.21%     
==========================================
  Files          74       74              
  Lines       10481    10530      +49     
  Branches     1432     1435       +3     
==========================================
+ Hits         9238     9260      +22     
- Misses       1216     1243      +27     
  Partials       27       27

Flag	Coverage Δ
suite.unit	`87.93% <49.05%> (-0.21%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…to huijbers/cdk-diagnose

github-actions · 2026-04-24T09:57:08Z

Total lines changed 2870 is greater than 1000. Please consider breaking this PR down.

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

…to huijbers/cdk-diagnose

mrgrain · 2026-04-28T09:28:03Z

      });

-      expect(stdErr).toContain('Import of existing resources failed');
+      expect(stdErr).toContain('needs a DeletionPolicy');


Why not keep both?

shrug. The message changed slightly. This is enough to confirm that the message is in the output.

mrgrain

Mostly minor stuff.

Bigger points for for me are:

Should the new command be --unstable for now?
The naming and jsdocs around OldestEvent don't click with me at all. Would love to see an iteration on the API to make the intent more clear.

mrgrain · 2026-04-28T09:30:50Z

+  /**
+   * Optionally a source trace
+   *
+   * (Not optional on purpose so we are not allowed to forget to call the code that should fill it)


Nice! Although this feels like a linter rules/TS config trying to come out 😱

I used to have branded types here but I also didn't want to expose those publicly, so this is the middle ground.

mrgrain · 2026-04-28T09:33:45Z

 /* c8 ignore stop */

-type TypeUnderlyingBrand<A> = A extends Branded<infer T, any> ? T : never;
+type TypeUnderlyingBrand<A> = Omit<A, keyof Brand<any>>;


Seems risky to go from never to any... Can you help explain this?

Sure.

The goal is, given Branded<A>, to find A. For whatever reason, the A extends Branded<infer T> never worked. I forget what it resolved to, but it was either any or unknown.

Since Branded<A> does A & Something, we can also try to remove the intersection. Googling told me that the way to de-intersect a type is to do Omit<A, keyof Something>. In our case the Something is a Brand<B>, but we don't care about the B because the keys are always the same, so B=any.

TL;DR: the never and any have nothing to do with each other, they just both happened to occur in 2 type manipulation signatures trying to do the same thing in a different way.

mrgrain · 2026-04-28T09:53:35Z

+// Some custom resource types that the CDK standard library creates that we
+// would like to see it if they fail.


thought (non-blocking): What a shame we don't have a consistent naming pattern for these 🤦🏻

mrgrain · 2026-04-28T09:57:49Z

+  shouldStop(event: ResourceEvent): 'stop-include' | 'stop-exclude' | 'continue';
+}
+
+export abstract class OldestEvent {


issue: The naming of this doesn't click with me.

mrgrain · 2026-04-28T09:58:47Z

+  public static timestamp(startTime: number): IOldestEvent {
+    return {
+      shouldStop(event) {
+        return event.event.Timestamp!.valueOf() < startTime ? 'stop-exclude' : 'continue';
+      },
+    };
+  }


fromTimestamp or withStartingPoint ?

OldestEvent.timestamp(...) just doesn't speak to me at all.

mrgrain · 2026-04-28T10:00:00Z

+after-the-fact.  This can be useful to refresh your memory, ask a colleague to
+help diagnose a deployment problem, or try to diagnose a deployment problem if
+your way of working dictates that you perform stack deployment via a CI/CD
+system (instead of directly using the CLI).


Suggested change

system (instead of directly using the CLI).

system instead of directly using the CDK CLI.

Co-authored-by: Momo Kornher <kornherm@amazon.co.uk>

rix0rrr temporarily deployed to automation April 16, 2026 14:57 — with GitHub Actions Inactive

rix0rrr requested a review from a team April 16, 2026 14:57

rix0rrr had a problem deploying to no-approval April 16, 2026 14:57 — with GitHub Actions Failure

aws-cdk-automation enabled auto-merge April 16, 2026 14:57

rix0rrr marked this pull request as draft April 16, 2026 14:57

auto-merge was automatically disabled April 16, 2026 14:57
Pull request was converted to draft

github-actions Bot added the p2 label Apr 16, 2026

aws-cdk-automation requested a review from a team April 16, 2026 14:59

rix0rrr had a problem deploying to no-approval April 21, 2026 10:49 — with GitHub Actions Failure

rix0rrr force-pushed the huijbers/cdk-diagnose branch from 67b63bc to 6fdb79a Compare April 21, 2026 12:00

rix0rrr had a problem deploying to no-approval April 21, 2026 12:00 — with GitHub Actions Failure

Remove this change

dd79e64

rix0rrr had a problem deploying to no-approval April 21, 2026 12:42 — with GitHub Actions Failure

Unused fn

eeba408

rix0rrr had a problem deploying to no-approval April 21, 2026 14:12 — with GitHub Actions Failure

Move some files aroudn

b8d1351

rix0rrr had a problem deploying to no-approval April 21, 2026 14:27 — with GitHub Actions Failure

rix0rrr added 4 commits April 22, 2026 12:00

Undo template changes

05c19b4

Fix some build errors

8af78e0

Merge remote-tracking branch 'origin/main' into huijbers/cdk-diagnose

d22d01c

Momo's changes

32986e3

rix0rrr had a problem deploying to no-approval April 22, 2026 10:57 — with GitHub Actions Failure

Merge remote-tracking branch 'origin/main' into huijbers/cdk-diagnose

6de53cd

rix0rrr had a problem deploying to no-approval April 22, 2026 10:57 — with GitHub Actions Failure

rix0rrr added 4 commits April 22, 2026 14:04

Stuff mostly compiles

b85cf2a

Fix diff tests

d39a102

Linter problems

b24f21c

Example file

fbd2bee

rix0rrr temporarily deployed to run-tests April 22, 2026 13:51 — with GitHub Actions Inactive

rix0rrr and others added 2 commits April 22, 2026 15:55

Fix another tiny thing

9ade17b

chore: self mutation

0736c9c

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

rix0rrr added 7 commits April 22, 2026 16:57

Linter

c18af16

Merge branch 'huijbers/cdk-diagnose' of github.com:aws/aws-cdk-cli in…

2bec3a8

…to huijbers/cdk-diagnose

Fix error message

7a5891e

Add formatting

b471fb3

Some formatting tweaks

10b7d98

Lookup role

6f44e5f

Tests

2bb46d3

rix0rrr and others added 4 commits April 24, 2026 13:49

Make sure the timestamp doesn't constantly change

023b4be

chore: self mutation

8924720

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update integ tests

3db1e9d

Merge branch 'huijbers/cdk-diagnose' of github.com:aws/aws-cdk-cli in…

53ff33b

…to huijbers/cdk-diagnose

mrgrain reviewed Apr 28, 2026

View reviewed changes

mrgrain requested changes Apr 28, 2026

View reviewed changes

Update packages/aws-cdk/README.md

4c71d7d

Co-authored-by: Momo Kornher <kornherm@amazon.co.uk>

		// Some custom resource types that the CDK standard library creates that we
		// would like to see it if they fail.

	system (instead of directly using the CLI).
	system instead of directly using the CDK CLI.

Conversation

rix0rrr commented Apr 16, 2026 • edited by mrgrain Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Apr 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrgrain left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rix0rrr Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rix0rrr commented Apr 16, 2026 •

edited by mrgrain

Loading

codecov-commenter commented Apr 22, 2026 •

edited

Loading

rix0rrr Apr 28, 2026 •

edited

Loading