cdk diff: Usage, Options & Common CI Errors

See what a cdk deploy would change before you run it.

cdk diff compares your synthesized stacks against what is currently deployed and prints the resource and IAM changes. As a PR gate it shows reviewers exactly what a deploy would do.

What it does

cdk diff synthesizes the app and diffs each stack against the deployed CloudFormation template, listing added/changed/removed resources, IAM and security-group changes, and parameter differences. With --fail it exits nonzero when there are differences, which is useful to flag drift or unreviewed changes in CI.

Common usage

# Diff one stack against what is deployed
cdk diff MyStack

# Diff all stacks
cdk diff --all

# Fail the job if there is any difference (drift gate)
cdk diff --all --fail

Common error in CI: credentials/region needed to read deployed state

diff fails with "Need to perform AWS calls ... but no credentials have been configured" or "Unable to resolve AWS account to use". diff must read the deployed template from CloudFormation, so it needs read credentials and an env. Fix: give the runner read-only AWS credentials and set the account/region (env on the stack or default profile). Use --fail only where you intend differences to break the build, since any deployed-vs-synth delta will trip it.

Key options

Related guides