cdk synth: Usage, Options & Common CI Errors

Synthesize your CDK app into CloudFormation templates.

cdk synth executes your CDK app and emits the CloudFormation template(s) it would deploy. It is the fast, credential-light gate to validate that an app synthesizes before any deploy.

What it does

cdk synth runs your app code, resolves constructs into a cloud assembly under cdk.out, and prints the CloudFormation template for a stack (or writes all of them). It does not contact AWS to deploy, though some context lookups (e.g. VPC/AMI) may require credentials unless cached in cdk.context.json.

Common usage

# Synthesize and print a stack template
cdk synth MyStack

# Synthesize all stacks into cdk.out (artifact for deploy)
cdk synth --all

# Quiet mode: write cdk.out without printing YAML
cdk synth --all -q

Common error in CI: context lookup needs credentials

synth fails with "Cannot retrieve value from context provider ... since account/region are not specified" or tries to call AWS for a Vpc.fromLookup. Fix: commit cdk.context.json so lookups are cached and synth runs offline, or supply read credentials plus an explicit env (account/region) on the stack. For a pure offline gate, avoid runtime lookups or pre-populate context with cdk context. Keep cdk.out as the artifact passed to the deploy job for an exact synth→deploy match.

Key options

Related guides