Fix: 'This stack uses assets' Error in AWS CDK

Why is CDK asking for a toolkit stack?

You hit cdk deploy and instead of a progress bar, you get a wall of text. The error looks like this:

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

This happens because your CDK code includes "assets." These are local files—like a 5MB Python Lambda function or a 200MB Docker image—that CloudFormation cannot handle directly. CDK needs a staging area to store these files before it can deploy your infrastructure.

The "toolkit stack" (named CDKToolkit) provides this staging area. It sets up an S3 bucket for file storage and IAM roles for deployment permissions. If you haven't initialized your AWS account and region, CDK has nowhere to put your code.

The Fix: Bootstrapping your environment

1. The standard command

The quickest fix is to run the exact command suggested in your terminal. Replace the account ID and region with your specific details:

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

Wait about 2–3 minutes. CDK will create a CloudFormation stack that provisions the necessary S3 bucket and encryption keys.

2. Working with AWS Profiles

If you use the --profile flag for deployments, you must use it for bootstrapping too. Failing to do this might result in bootstrapping the wrong AWS account.

cdk bootstrap --profile prod-account aws://123456789012/us-east-1

3. Deploying to multiple regions

Bootstrapping is region-specific. If your app spans us-east-1 (N. Virginia) and us-west-2 (Oregon), you need to run the command for both. CDK will create a separate CDKToolkit stack in each region to ensure assets are stored locally for faster deployments.

4. Solving Permission Denied errors

Bootstrapping creates IAM roles and S3 buckets, which are high-privilege actions. If you see an "Access Denied" error, your current IAM user likely lacks the AdministratorAccess policy. Ask your admin for temporary elevated permissions or have them run the bootstrap command for you.

How to verify the fix

Don't just take the terminal's word for it. You can see the infrastructure CDK built by checking these areas:

• CloudFormation: Look for a stack named CDKToolkit. It should show a CREATE_COMPLETE status.
• S3 Console: You will find a new bucket named cdk-hnb659fds-assets-[account]-[region]. This is where your Lambda .zip files will live.
• IAM: Several roles starting with cdk-hnb659fds- will be created to handle file publishing and CloudFormation execution.

Best Practices

One-time setup: You only need to bootstrap an account/region once. There is no need to include cdk bootstrap in your GitHub Actions or Jenkins pipeline scripts. Doing so just adds unnecessary time to your CI/CD runs.

CDK v1 vs v2: If you recently upgraded from CDK v1 to v2, you might need to re-bootstrap. CDK v2 uses a "Modern" bootstrapping template that offers better security and support for cross-account deployments than the legacy version.

Costs: The S3 bucket created is virtually free if it's empty. You only pay for the storage of the assets you upload. If you notice your AWS bill creeping up, check the bucket and prune old versions of your Lambda functions or Docker images.