cdk bootstrap: Usage, Options & Common CI Errors

Provision the resources CDK needs before it can deploy to an account.

cdk bootstrap creates the CDKToolkit stack - an S3 bucket, ECR repo, and IAM roles - that CDK uses to stage assets and deploy. Every account+region pair must be bootstrapped once before deploy.

What it does

cdk bootstrap deploys a CloudFormation stack (CDKToolkit) holding the staging bucket, image repository, and deployment roles CDK relies on, plus an SSM parameter recording the bootstrap version. Modern CDK uses the "modern" bootstrap template with deploy roles; cross-account deploys add --trust.

Common usage

# Bootstrap the current account/region
cdk bootstrap

# Bootstrap an explicit account and region
cdk bootstrap aws://123456789012/us-east-1

# Trust another account to deploy into this one (CI/CD pipelines)
cdk bootstrap aws://123456789012/us-east-1 \
  --trust 999999999999 \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess

Common error in CI: insufficient permissions / version mismatch

bootstrap fails with "User is not authorized to perform: cloudformation:CreateStack" (the principal cannot create the toolkit) or deploys later complain the bootstrap stack version is too old. Fix: run bootstrap with an admin-capable principal once per account+region, and re-run cdk bootstrap after upgrading the CDK CLI so the toolkit version keeps pace (deploy checks the SSM version parameter). For pipelines, bootstrap the target account with --trust for the pipeline account.

Key options

Related guides