[xyos]

Problem

In an account and Region that were never CDK-bootstrapped, npm run deploy and npm run sandbox fail only after synthesis and the asset builds, with:

SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped?

The preflight checks credentials but not bootstrap. The CDK error does not name the account or Region, and a plain npx cdk bootstrap aws://<account>/<region> run in a Blocks project synthesizes the whole app first, because CDK synthesizes whenever cdk.json has an app, even with an explicit environment (CdkToolkit.defineEnvironments).

Issue #, if available:

Changes

• Bootstrap check in the credential preflight (preflight-bootstrap.ts, wired through assertAwsCredentials({ checkBootstrap: true }) from deploy() and startSandbox()). After STS verifies the credentials, it reads /cdk-bootstrap/<qualifier>/version with those same credentials, in the deploy Region, in parallel with the existing account-metadata reads (one attempt, 1 s connect / 2 s request timeout).
• Only ParameterNotFound stops the deploy. The deployment target is printed first, then the command stops with:

  CDK is not bootstrapped in Region eu-south-2 of account 111122223333, so `npm run deploy` cannot deploy there (SSM parameter /cdk-bootstrap/hnb659fds/version not found).
    Bootstrap once per account and Region. From this project directory, run:
      npx cdk bootstrap aws://111122223333/eu-south-2 --app=
    This creates the CDKToolkit CloudFormation stack: the S3 bucket, ECR repository and IAM roles that CDK deploys with.
    ...
  Then re-run `npm run deploy`.
  

  --app= stops cdk bootstrap from synthesizing the app. From the project directory, CDK still reads the cdk.json profile and qualifier. A denied read, a network error, a timeout or any other error is inconclusive and the deploy continues. CDK reads this parameter through its bootstrap roles, so credentials that cannot read it may still deploy.
• Qualifier: resolveDeploymentTarget now also returns @aws-cdk/core:bootstrapQualifier, from cdk.json context, then cdk.context.json, then ~/.cdk.json context. That is the CLI's lookup order (Configuration.loadConfigFiles). A malformed cdk.context.json is ignored here; CDK reports it itself. A qualifier that the bootstrap template rejects skips the check.
• STS probe now also returns Account, used for the command.
• No auto-bootstrap. Bootstrapping creates IAM roles, including the CloudFormation execution role (AdministratorAccess by default), in the user's account. That should stay the user's call, not a side effect of npm run deploy. The app AGENTS.md tells coding agents to ask the user before running it.
• Destroy commands do not run the check.
• Docs: Blocks README (deploy section) and the app AGENTS.md. Changeset for core, blocks and create-blocks-app.

Known limit: an app that sets a custom qualifier only in code (synthesizer: new DefaultStackSynthesizer({ qualifier })) and not in context would be checked against the default qualifier. The message says to set the same value as @aws-cdk/core:bootstrapQualifier in cdk.json, which the synthesizer also reads.

Validation

• New preflight-bootstrap.test.ts:
  • deploy and sandbox stop with the command, after printing the target.
  • The reader gets the deploy Region, profile, verified credentials and parameter name.
  • Qualifier and profile come from cdk.json.
  • The parameter is present, or the read is denied, times out, hits a network error or rejects with a non-Error: the deploy continues.
  • The check is skipped when it's off, when there's no account, and for an invalid qualifier.
  • A shell-unsafe Region prints as <region>.
• New deployment-target.test.ts cases: qualifier precedence, and malformed cdk.context.json.
• npm run build, npm run lint, npm run lint:deps: pass. Root npm test (all workspaces): exit 0, no failures; core alone is 1611 pass, 0 fail. npm run test:e2e:local: 0 failures.
• Smoke, real deploy() path: a temp project, with AWS_ENDPOINT_URL pointed at a local fake STS/SSM endpoint. The real SDK clients and error mapping were used, with no AWS account.
  • Missing parameter: exits 1 in 0.8 s with the message above. The SSM request was signed for ssm@eu-south-2, and the cdk.json app (a marker script) never ran.
  • Parameter present, or AccessDeniedException: passes the preflight and continues to client codegen.
• --app= behavior (aws-cdk 2.1138.0): cdk bootstrap aws://… in a directory whose cdk.json has an app ran the app. With --app=, the app did not run, and the CLI went straight to Bootstrapping environment aws://….
• Real account (built deploy() and startSandbox() with an AWS profile, from a throwaway project with no backend):
  • sa-east-1 (not bootstrapped, confirmed with aws ssm get-parameter): deploy and sandbox each exited 1 in about 2 s with the message above. The account and Region in the printed command were correct, the app in cdk.json never ran, and no CloudFormation call was made.
  • us-east-1 (bootstrapped, version 32): passed the check and continued to client codegen, then failed because the throwaway project has no backend. CDK never ran.
• Not run: a full deploy after running the printed cdk bootstrap command.

Checklist

• PR description included
• Tests are changed or added
• Relevant documentation is changed or added (and PR referenced)

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[changeset-bot]

🦋 Changeset detected

Latest commit: 13e9380

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@aws-blocks/core	Patch
@aws-blocks/blocks	Patch
@aws-blocks/create-blocks-app	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR