AWS CDK "This stack uses assets, so the toolkit stack must be deployed" in CI

By Kaveh Alemi·Latchkey

Your stack publishes assets (Lambda code, Docker images, large templates) to the CDK staging bucket and ECR repo. Those live in the bootstrap (toolkit) stack, and the target account/region has none yet, so deploy refuses to start.

What this error means

cdk deploy stops immediately with "This stack uses assets, so the toolkit stack must be deployed to the environment (Run \"cdk bootstrap aws://ACCOUNT/REGION\")". It happens the first time you deploy to a fresh account or region.

❌  MyAppStack failed: Error: MyAppStack: This stack uses assets, so the toolkit
stack must be deployed to the environment (Run "cdk bootstrap aws://123456789012/us-east-1")

Common causes

The account/region is not bootstrapped

CDK deploys with assets require the CDKToolkit stack (staging S3 bucket, ECR repo, deploy roles). A new account or a new region has never had cdk bootstrap run against it.

CI uses a different region than the bootstrapped one

You bootstrapped us-east-1 but the job sets AWS_REGION=eu-west-1, so CDK looks for a toolkit stack that does not exist there.

How to fix it

Bootstrap the target environment once

1. Run cdk bootstrap against the exact account and region the job deploys to.
2. Use modern bootstrapping so deploy roles and the staging bucket are created.
3. Re-run the deploy; the toolkit stack now exists.

cdk bootstrap aws://123456789012/us-east-1

Bootstrap as a gated CI step

Add a bootstrap step that runs idempotently before deploy, so new regions self-provision.

- run: npx cdk bootstrap aws://${{ env.ACCOUNT }}/${{ env.AWS_REGION }}

How to prevent it

• Bootstrap every target account and region before the first asset deploy.
• Keep the deploy region consistent between bootstrap and CI.
• Re-bootstrap when you upgrade the CDK CLI major version.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation