What Does CDK Bootstrap Do? Setup Guide + Troubleshooting

Running cdk deploy and getting "SSM parameter not found" errors? Or confused about what cdk bootstrap actually creates in your AWS account?

You're not alone. CDK bootstrap is the critical first step that most tutorials gloss over, until you hit permission errors or need cross-account deployments. The command itself is simple, but understanding what it does and when to re-run it separates smooth CDK workflows from frustrating debugging sessions.

This guide covers exactly what bootstrap creates, the correct command syntax for any scenario, how to fix common errors, and enterprise multi-account setup. Based on AWS CDK v2 documentation and bootstrap template version 27 (current as of January 2026).

If you're new to the AWS Cloud Development Kit (AWS CDK), start with our beginner's guide before diving into bootstrap setup.

TL;DR: Quick Reference

Here's the command you need to bootstrap your AWS environment:

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

Replace 123456789012 with your AWS account ID and us-east-1 with your target region.

What this creates:

• CDKToolkit CloudFormation stack
• S3 bucket for file assets (cdk-hnb659fds-assets-<account>-<region>)
• ECR repository for Docker images (cdk-hnb659fds-container-assets-<account>-<region>)
• 5 IAM roles for deployment permissions
• SSM parameter for version tracking (/cdk-bootstrap/hnb659fds/version)

Now let's understand what's actually happening when you run this command.

What is CDK Bootstrap?

CDK bootstrap prepares your AWS environment for CDK deployments by creating the infrastructure that the CDK CLI needs to deploy your applications. Think of it as laying the foundation before building a house.

Before any AWS CDK app can be deployed, you need to install AWS CDK and bootstrap each target environment. An "environment" in CDK terms is a specific AWS account and region combination, for example, account 123456789012 in us-east-1 is one environment, while the same account in eu-west-1 is a different environment.

Why is bootstrap required? CDK deployments need somewhere to store assets (Lambda code, CloudFormation templates, Docker images) and specific IAM roles to execute CloudFormation operations securely. Without these resources, cdk deploy simply fails.

What Does CDK Bootstrap Do?

When you run cdk bootstrap, the CDK CLI deploys a CloudFormation stack named CDKToolkit that provisions all the resources needed for subsequent CDK deployments.

How Bootstrap Works

The execution flow is straightforward:

1. CDK CLI retrieves the bootstrap template (embedded in the CLI or from a specified file)
2. Deploys the template to CloudFormation as a stack named CDKToolkit
3. CloudFormation provisions all bootstrap resources in your target environment
4. Creates an SSM parameter to track the bootstrap stack version
5. Bootstrap stack appears in CloudFormation console after successful deployment

The CDK team maintains the canonical bootstrap template in the aws-cdk-cli GitHub repository.

What Resources Get Created

Let me walk you through each resource that bootstrap creates.

Amazon S3 Bucket

The S3 bucket stores your CDK file assets, Lambda function code, and CloudFormation templates.

• Name pattern: cdk-hnb659fds-assets-<account-id>-<region>
• Example: cdk-hnb659fds-assets-123456789012-us-east-1
• Encryption: AWS managed KMS key by default
• Public access: Blocked
• Lifecycle: Noncurrent objects retained for 30 days (changed from 365 days in version 24)

Amazon ECR Repository

The ECR repository stores Docker image assets for containerized applications.

• Name pattern: cdk-hnb659fds-container-assets-<account-id>-<region>
• Example: cdk-hnb659fds-container-assets-123456789012-us-east-1
• Image mutability: Immutable (images cannot be overwritten)
• Scan on push: Enabled by default

Five IAM Roles

Bootstrap creates five IAM roles, each with a specific purpose. Understanding these roles is essential for troubleshooting permission issues.

SSM Parameter

• Name: /cdk-bootstrap/hnb659fds/version
• Purpose: Tracks bootstrap stack version (currently version 27)
• Used by: CDK CLI to verify bootstrap compatibility before deployments

The following diagram shows how these resources relate to each other within the CDKToolkit CloudFormation stack:

Now that you understand what gets created, let's look at the command syntax options.

CDK Bootstrap Command Syntax

The basic syntax is simple, but the command has powerful options for advanced scenarios.

Basic Command

cdk bootstrap aws://ACCOUNT-ID/REGION

The aws:// prefix is optional, so this also works:

cdk bootstrap ACCOUNT-ID/REGION

Environment Argument

If you run cdk bootstrap from within a CDK project directory without specifying an environment, the CLI determines the target from:

1. Environments referenced in your CDK app
2. The --profile option
3. Default AWS credentials and config files
4. Environment variables (AWS_ACCOUNT_ID, AWS_REGION)

To bootstrap multiple environments in a single command:

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

Key Command Options

Here are the most important options you'll use:

Important about --trust: When updating an existing bootstrap stack to add new trusted accounts, you must specify ALL accounts to trust (existing and new). Otherwise, previously trusted accounts are removed.

Let's walk through running bootstrap step by step.

Step-by-Step: Running CDK Bootstrap

Prerequisites

Before bootstrapping, ensure you have:

1. AWS CDK CLI installed - Follow our CDK installation guide
2. AWS credentials configured - Either via environment variables, AWS CLI profiles, or IAM Identity Center
3. Sufficient IAM permissions - You need permissions for CloudFormation, S3, ECR, IAM, and SSM

The minimum IAM permissions required for bootstrapping:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:*",
                "ecr:*",
                "ssm:*",
                "s3:*",
                "iam:*"
            ],
            "Resource": "*"
        }
    ]
}

Single Account Bootstrap

1. Get your AWS account ID and region:

# Get your account ID
aws sts get-caller-identity --query "Account" --output text

# Get your default region
aws configure get region

2. Run the bootstrap command:

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

3. Verify the output:

 ⏳  Bootstrapping environment aws://123456789012/us-east-1...
Trusted accounts for deployment: (none)
Trusted accounts for lookup: (none)
Execution policies: arn:aws:iam::aws:policy/AdministratorAccess
CDKToolkit: creating CloudFormation changeset...
 ✅  Environment aws://123456789012/us-east-1 bootstrapped.

Verifying Bootstrap Success

You can verify bootstrap completed successfully in several ways:

Check CloudFormation stack:

aws cloudformation describe-stacks \
  --stack-name CDKToolkit \
  --query "Stacks[0].StackStatus" \
  --output text

Expected output: CREATE_COMPLETE or UPDATE_COMPLETE

Check bootstrap version via SSM parameter:

aws ssm get-parameter \
  --name /cdk-bootstrap/hnb659fds/version \
  --query "Parameter.Value" \
  --output text

Expected output: 27 (or current version)

Check via CloudFormation stack output:

aws cloudformation describe-stacks \
  --stack-name CDKToolkit \
  --query "Stacks[0].Outputs[?OutputKey=='BootstrapVersion'].OutputValue" \
  --output text

Common CDK Bootstrap Errors and Fixes

When bootstrap fails, the error messages can be cryptic. Here's how to diagnose and fix the most common issues.

"Specify an environment name" Error

Error message:

Error: Please pass the desired environment ('aws://ACCOUNT/REGION') as an argument to 'cdk bootstrap'. You can also configure the environment via the 'env' property in your stack.

Cause: Running cdk bootstrap outside a CDK project directory without specifying the environment.

Solution: Explicitly provide the environment:

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

Or use a profile:

cdk bootstrap --profile prod

How to find your account ID and region:

aws sts get-caller-identity
aws configure get region

"SSM parameter not found" Error

Error message:

Deployment failed: Error: MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found.
Has the environment been bootstrapped? Please run 'cdk bootstrap'

Cause: The target environment hasn't been bootstrapped yet.

Solution: Bootstrap the environment before deploying:

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

"S3 Bucket already exists" Error

Error message:

CREATE_FAILED | AWS::S3::Bucket | cdk-hnb659fds-assets-123456789012-us-east-1 already exists

Cause: S3 bucket names are globally unique. The generated name conflicts with an existing bucket (possibly in a different account or from a previous bootstrap attempt).

Solutions:

Option 1: Use a custom bucket name:

cdk bootstrap --bootstrap-bucket-name my-unique-cdk-bucket-12345 aws://123456789012/us-east-1

Option 2: Use a different qualifier:

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

Note: If you change the qualifier, you must also configure your CDK app to use it.

Permission Errors During Bootstrap

Symptoms: Various "AccessDenied" or "not authorized" errors during bootstrap.

Cause: Your IAM user or role lacks the required permissions.

Solution: Ensure your credentials have the permissions listed in the Prerequisites section above. If you're using Service Control Policies, verify they don't block required actions.

Bootstrap Version Mismatch

Error message:

This CDK CLI is not compatible with the CDK library used by your application. Please upgrade the CLI to the latest version.

Cause: Your CDK app requires a newer bootstrap version than what's deployed.

Solution: Update your bootstrap stack:

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

Bootstrapping is idempotent. It upgrades the stack if a newer version is available or does nothing if already current.

"Policy contains invalid principals" Error

Error message:

Policy contains a statement with one or more invalid principals

Cause: Using CDK Pipelines to deploy to another account that hasn't been bootstrapped with the proper trust relationship.

Solution: Bootstrap the target account with the --trust flag:

cdk bootstrap aws://222222222222/us-east-1 \
  --trust 111111111111 \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess

Where 111111111111 is your pipeline account ID.

If you're setting up deployments across multiple AWS accounts, the next section covers that in detail.

Multi-Account Bootstrap Setup

Cross-account deployments are common in enterprise environments, especially when using CDK Pipelines for CI/CD. Understanding multi-account bootstrap is essential for implementing a proper multi-account strategy.

When You Need Multi-Account Bootstrap

You need multi-account bootstrap when:

• Using CDK Pipelines to deploy from a central pipeline account to target accounts
• Implementing a multi-account architecture with separate accounts for dev, staging, and production
• Centralizing deployments in a shared services account

Bootstrap with --trust Flag

The key to cross-account deployments is the --trust flag. Here's how the trust relationship works:

CDK Pipelines Bootstrap Requirements

CDK Pipelines require the modern bootstrap template. Bootstrap all environments (pipeline account and all deployment targets) before creating your pipeline.

Step 1: Bootstrap the pipeline account

cdk bootstrap aws://111111111111/us-east-1 \
  --profile pipeline-admin \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess

Step 2: Bootstrap target accounts with trust

cdk bootstrap aws://222222222222/us-east-1 \
  --profile target-admin \
  --trust 111111111111 \
  --trust-for-lookup 111111111111 \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess

The --trust-for-lookup flag allows the pipeline account to perform context lookups during synthesis.

Adding Trust to Existing Bootstrap Stack

To add a new trusted account to an already bootstrapped environment:

cdk bootstrap aws://222222222222/us-east-1 \
  --trust 111111111111 \
  --trust 333333333333 \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess

Critical: You must specify ALL accounts to trust (existing and new). If you only provide the new account, previously trusted accounts will be removed.

Security warning: Anyone with access to trusted accounts effectively has all permissions conferred by the CloudFormation execution policies. The default AdministratorAccess allows trusted accounts to create arbitrary infrastructure. Restrict the --trust list and consider using more restrictive execution policies for production environments.

For those who need more control, you can also bootstrap using CloudFormation directly.

CDK Bootstrap vs Manual Setup

Most teams should use cdk bootstrap directly. But in some enterprise scenarios, you might need manual control over the bootstrap process.

When to Use CDK Bootstrap (Recommended)

Use the standard cdk bootstrap command when:

• Bootstrapping a small number of environments (1-10)
• You want automatic version management
• Speed and simplicity are priorities
• Standard bootstrap configuration meets your needs

Advantages: Fast, single command, automatically maintained by AWS, built-in cross-account support.

When to Use CloudFormation Directly

Consider manual CloudFormation deployment when:

• Bootstrapping dozens or hundreds of environments simultaneously
• Your organization requires CloudFormation approval processes
• You need custom modifications to the bootstrap template
• Using AWS Control Tower or CloudFormation StackSets
• Specific compliance requirements mandate template review

How to export the template:

cdk bootstrap --show-template > bootstrap-template.yaml

Deploy with CloudFormation:

aws cloudformation create-stack \
  --stack-name CDKToolkit \
  --template-body file://bootstrap-template.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --region us-east-1

Deploy a custom template with CDK:

cdk bootstrap --template custom-bootstrap-template.yaml aws://123456789012/us-east-1

Whether you bootstrap manually or with the CLI, you'll occasionally need to re-bootstrap.

When to Re-Bootstrap Your Environment

Bootstrapping isn't a one-time activity. Here's when you need to run it again.

Template version updates: The CDK team periodically releases new bootstrap template versions (currently version 27). New versions add features, fix issues, and address security findings. Re-bootstrap to get the latest version.

Adding cross-account trust: When you need to allow new accounts to deploy into your environment, re-bootstrap with updated --trust flags. Remember to include all previously trusted accounts.

Changing execution policies: To update the IAM policies attached to CloudFormationExecutionRole:

cdk bootstrap aws://123456789012/us-east-1 \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/PowerUserAccess

Enabling termination protection: Can be added to existing bootstrap stacks:

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

Migrating from CDK v1 to v2: CDK v2 requires the modern bootstrap template. Legacy CDK v1 environments must be re-bootstrapped.

Safe to run multiple times: Bootstrap is idempotent. If your environment is already bootstrapped with the current version, the command does nothing. If it's outdated, the stack upgrades. If not bootstrapped, a new stack is created.

To understand where bootstrap fits in the CDK workflow, let's compare it to other CDK commands.

CDK Commands Comparison

Understanding how cdk bootstrap relates to other CDK commands helps you grasp the overall CDK workflow.

Typical workflow:

1. cdk bootstrap aws://ACCOUNT/REGION
   ↓ (One-time setup, creates CDK infrastructure)

2. cdk synth
   ↓ (Validate code, review generated templates)

3. cdk diff
   ↓ (Preview what will change)

4. cdk deploy
   ↓ (Deploy to AWS)

(Repeat steps 2-4 for iterative development)

Key relationship:

• cdk bootstrap creates infrastructure FOR the CDK CLI
• cdk synth creates templates FROM your CDK code
• cdk diff compares templates WITH deployed state
• cdk deploy deploys templates USING bootstrap resources

For a deeper dive into these commands, see our CDK best practices guide.

Now let's cover security best practices for your bootstrap stack.

Bootstrap Security Best Practices

The bootstrap stack is foundational infrastructure. Securing it properly is critical.

Termination Protection

Always enable termination protection for production environments:

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

Deleting the bootstrap stack causes all CDK deployments to fail with no general recovery solution. Termination protection prevents accidental deletion.

Least Privilege Execution Policies

The default --cloudformation-execution-policies grants AdministratorAccess, giving CloudFormation (and by extension, trusted accounts) full access to your AWS account.

For production environments, consider restricting these policies:

cdk bootstrap aws://123456789012/us-east-1 \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/PowerUserAccess

Or create custom policies scoped to your specific resource types.

Security Hub Findings

You might encounter AWS Security Hub finding KMS.2 related to the DeploymentActionRole's inline policy. This finding flags policies with Resource: * and KMS decrypt permissions.

Why it exists: The role needs access to cross-account KMS keys created by CDK Pipelines, which don't exist at bootstrap time.

Actual risk: Low. The policy includes a Condition clause restricting access to same-account KMS keys used by S3 in the same region. Security Hub doesn't evaluate conditions when flagging.

If you're not using CDK Pipelines and want to fix it:

1. Export the template: cdk bootstrap --show-template > bootstrap-template.yaml
2. Remove the PipelineCrossAccountArtifactsBucket and PipelineCrossAccountArtifactsKey statements
3. Deploy: cdk bootstrap --template bootstrap-template.yaml aws://ACCOUNT/REGION

Got questions? Check our FAQ section below.

Conclusion

CDK bootstrap is foundational to every CDK deployment. Here's what to remember:

1. Bootstrap once per account/region combination before any CDK deployments
2. Use the --trust flag for cross-account deployments with CDK Pipelines
3. Re-bootstrap to upgrade versions. The command is idempotent and safe to run multiple times
4. Enable termination protection in production environments

Your next step: Bootstrap your development environment now:

cdk bootstrap aws://YOUR-ACCOUNT-ID/YOUR-REGION

Ready to deploy your first CDK stack? See our CDK best practices guide for production-ready patterns, or learn about CDK stacks and CDK constructs to deepen your understanding.

Frequently Asked Questions