🚨 IaC Error Guide: 'Has the environment been bootstrapped?' AWS CDK Deploy

Overview

This error happens when cdk deploy tries to use the bootstrap resources (the staging S3 bucket, ECR repo, SSM version parameter, and IAM roles created by cdk bootstrap) but they are missing, out of date, or in a different account/region than CDK expects. CDK synthesizes a template that references the bootstrap qualifier and roles, then fails when it cannot find them.

You will see this when running cdk deploy:

current credentials could not be used to assume 'arn:aws:iam::123456789012:role/cdk-hnb659fds-deploy-role-123456789012-us-east-1',
but are for the right account. Proceeding anyway.

❌  MyAppStack failed: Error: MyAppStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found.
Has the environment been bootstrapped? Please run 'cdk bootstrap'
(see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)

It occurs because CDK deployments are environment-specific: every distinct account/region pair must be bootstrapped once. A stack that deploys fine in us-east-1 will fail in eu-west-1 until that region is bootstrapped too, and a stale bootstrap version will block deploys after a CDK upgrade.

Symptoms

• cdk deploy fails with SSM parameter /cdk-bootstrap/<qualifier>/version not found.
• The error literally asks Has the environment been bootstrapped?.
• The CDKToolkit CloudFormation stack is absent in the target account/region.
• A deploy that worked yesterday now fails with a bootstrap-version mismatch after upgrading the CDK CLI.

cdk deploy MyAppStack

✨  Synthesis time: 3.2s

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

Common Root Causes

1. The environment was never bootstrapped (no CDKToolkit stack)

The target account/region has no CDKToolkit stack, so none of the bootstrap resources exist.

aws cloudformation describe-stacks --stack-name CDKToolkit --region us-east-1

An error occurred (ValidationError) when calling the DescribeStacks operation:
Stack with id CDKToolkit does not exist

No CDKToolkit stack means the environment must be bootstrapped before any deploy.

2. Deploying to the wrong account or region

Your credentials or CDK_DEFAULT_REGION point at a different environment than the one that was bootstrapped.

aws sts get-caller-identity
echo "region=$CDK_DEFAULT_REGION / $AWS_REGION"

{
    "Account": "987654321098",
    "Arn": "arn:aws:iam::987654321098:user/ci-deployer"
}
region=eu-west-1 /

The stack targets account 123456789012 but the active credentials are for 987654321098, so the bootstrap lookup fails.

3. Mismatched bootstrap version after a CDK upgrade

The bootstrap stack exists but is too old for the current CLI. CDK compares the /cdk-bootstrap/<qualifier>/version SSM parameter against the version it requires.

aws ssm get-parameter --name /cdk-bootstrap/hnb659fds/version \
  --region us-east-1 --query 'Parameter.Value' --output text

14

❌  MyAppStack failed: This CDK deployment requires bootstrap stack version '21',
found '14'. Please run 'cdk bootstrap'.

The installed CLI needs bootstrap version 21 but the environment is stuck at 14.

4. Insufficient IAM permissions to bootstrap or deploy

The principal cannot create the bootstrap stack (or assume the generated deploy role), so bootstrap fails or deploy cannot proceed.

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

 ⏳  Bootstrapping environment aws://123456789012/us-east-1...
❌  Environment aws://123456789012/us-east-1 failed bootstrapping:
User: arn:aws:iam::123456789012:user/ci-deployer is not authorized to perform:
cloudformation:CreateStack on resource: arn:aws:cloudformation:us-east-1:123456789012:stack/CDKToolkit/*

The deployer lacks the CloudFormation/IAM permissions bootstrap needs to create roles and the toolkit stack.

5. Cross-account trust not configured

For pipeline/cross-account deploys, the target environment must be bootstrapped to trust the deploying account, or the assume-role step fails.

aws iam get-role --role-name cdk-hnb659fds-deploy-role-123456789012-us-east-1 \
  --query 'Role.AssumeRolePolicyDocument.Statement[0].Principal'

{
    "AWS": "arn:aws:iam::123456789012:root"
}

current credentials could not be used to assume
'arn:aws:iam::123456789012:role/cdk-hnb659fds-deploy-role-...': Access denied

The deploy role only trusts 123456789012, but the pipeline runs in 555555555555 — bootstrap the target with --trust 555555555555.

6. Bootstrap qualifier mismatch

The app was synthesized with a custom @aws-cdk/core:bootstrapQualifier, but the environment was bootstrapped with the default hnb659fds (or vice versa), so the SSM path CDK looks up does not exist.

grep -r 'bootstrapQualifier' cdk.json
aws ssm describe-parameters --region us-east-1 \
  --query "Parameters[?contains(Name, 'cdk-bootstrap')].Name"

"@aws-cdk/core:bootstrapQualifier": "myco1234"
[
    "/cdk-bootstrap/hnb659fds/version"
]

The app expects qualifier myco1234 but only hnb659fds was bootstrapped — the version lookup at /cdk-bootstrap/myco1234/version misses.

Diagnostic Workflow

Step 1: Confirm the target environment

aws sts get-caller-identity --query 'Account' --output text
cdk deploy MyAppStack 2>&1 | grep -i 'aws://'

Establish the exact account/region the stack targets versus the account your credentials belong to. A mismatch here is the most common false alarm.

Step 2: Check whether CDKToolkit exists

aws cloudformation describe-stacks --stack-name CDKToolkit \
  --region us-east-1 --query 'Stacks[0].StackStatus' --output text

If this errors with does not exist, the environment was never bootstrapped (cause 1).

Step 3: Read the bootstrap version parameter

aws ssm get-parameter --name /cdk-bootstrap/hnb659fds/version \
  --region us-east-1 --query 'Parameter.Value' --output text

Compare against the version your CLI requires (shown in the error). A lower number means a re-bootstrap is needed (cause 3).

Step 4: Verify the qualifier matches

grep -r 'bootstrapQualifier' cdk.json
aws ssm describe-parameters --region us-east-1 \
  --query "Parameters[?contains(Name, 'cdk-bootstrap')].Name"

The qualifier in cdk.json must match the /cdk-bootstrap/<qualifier>/version path that exists (cause 6).

Step 5: Run cdk doctor and re-bootstrap

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

cdk doctor reports CLI/library versions and environment variables. A plain cdk bootstrap (re-run) is idempotent and upgrades an existing toolkit stack to the required version.

Example Root Cause Analysis

A CI job that has deployed MyAppStack to us-east-1 for months suddenly fails after the team bumped the CDK CLI in the build image.

The error is explicit about a version gap:

❌  MyAppStack failed: This CDK deployment requires bootstrap stack version '21',
found '14'. Please run 'cdk bootstrap'.

Confirming the live bootstrap version:

aws ssm get-parameter --name /cdk-bootstrap/hnb659fds/version \
  --region us-east-1 --query 'Parameter.Value' --output text

14

The environment is on bootstrap version 14, but the upgraded CLI emits templates that require version 21. The toolkit stack itself is fine — it just needs to be upgraded. Re-running bootstrap updates the CDKToolkit stack and its SSM version in place:

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

 ⏳  Bootstrapping environment aws://123456789012/us-east-1...
 ✅  Environment aws://123456789012/us-east-1 bootstrapped
    (no changes to S3 bucket; roles updated; version 14 -> 21).

With the bootstrap stack now at version 21, cdk deploy MyAppStack succeeds. The lasting fix is to pin the CDK CLI version in the build image and re-bootstrap deliberately as part of upgrades, rather than letting a floating CLI drift ahead of the environment.

Prevention Best Practices

• Bootstrap every account/region your stacks target as a one-time, codified step, and re-bootstrap explicitly whenever you upgrade the CDK CLI. Track this alongside the rest of your infrastructure-as-code guides.
• Pin the CDK CLI version in CI so the required bootstrap version cannot silently jump ahead of the environment.
• Keep the bootstrapQualifier consistent between cdk.json and how the environment was bootstrapped; if you use a custom qualifier, bootstrap with --qualifier.
• For pipelines, bootstrap target accounts with --trust <pipeline-account> and --cloudformation-execution-policies so cross-account assume-role works.
• Grant the bootstrap principal the CloudFormation/IAM/S3/ECR permissions it needs up front; least-privilege deploy roles come from the toolkit stack, not from the human running deploy.
• When a deploy fails under pressure, the free incident assistant can turn the CDK error into the likely missing-bootstrap or version-mismatch cause.

Quick Command Reference

# Confirm the account/region you are actually deploying to
aws sts get-caller-identity --query 'Account' --output text

# Does the bootstrap (CDKToolkit) stack exist?
aws cloudformation describe-stacks --stack-name CDKToolkit --region us-east-1

# What bootstrap version is live?
aws ssm get-parameter --name /cdk-bootstrap/hnb659fds/version \
  --region us-east-1 --query 'Parameter.Value' --output text

# Check the qualifier the app expects
grep -r 'bootstrapQualifier' cdk.json

# Environment / version sanity check
cdk doctor

# Bootstrap or upgrade the environment (idempotent)
cdk bootstrap aws://123456789012/us-east-1

# Cross-account / pipeline bootstrap
cdk bootstrap --trust 555555555555 \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess \
  aws://123456789012/us-east-1

# Retry the deploy
cdk deploy MyAppStack

Conclusion

The CDK Has the environment been bootstrapped? error means cdk deploy could not find the bootstrap resources it depends on in the target account/region. The usual root causes:

1. The environment was never bootstrapped, so the CDKToolkit stack is absent.
2. Credentials or region point at a different account/region than the stack targets.
3. The bootstrap version is stale after a CDK CLI upgrade.
4. The principal lacks IAM permissions to bootstrap or assume the deploy role.
5. Cross-account trust was not configured during bootstrap.
6. The bootstrapQualifier in the app does not match how the environment was bootstrapped.

Confirm the real account/region first, check CDKToolkit and the SSM version parameter, then re-run cdk bootstrap — it is idempotent and repairs both missing and stale environments.