AWS CDK CLI errors
Look up a cdk synth, bootstrap or deploy failure by its text — assume-role failures on cdk-hnb659fds roles, wrong-account credentials, SSM bootstrap parameter not found, bootstrap version too old, NoSuchBucket, forbidden null, staging bucket already exists, --app is required, too many resources (Number of resources in stack), stack in a failed state, version mismatch, only two AZs, resources not deleted on destroy — with cause and fix.
markdownreferencev4MGG0-0X5Mstage: operatetrust: officialservice: cdkinterface: cliinterface: iacCould not assume role in target accountcdk-hnb659fds-deploy-role AccessDeniedNeed to perform AWS calls for accountbut the current credentials are forSSM parameter /cdk-bootstrap/hnb659fds/version not foundHas the environment been bootstrappedrequires bootstrap stack versionBootstrap stack version is requiredNoSuchBucketforbidden nullcdk-hnb659fds-assets already exists--app is requiredTemplate too large to deployis in a failed statecloud assembly schema version mismatchCDK only two availability zonescdk destroy bucket not deletedAssuming role failed ExpiredTokenProceeding anyway
Most CDK deploy failures are about the bootstrap: it's missing, too old, or your identity can't assume its roles. Errors raised by CloudFormation during the deploy are in reference/cloudformation/errors.md. The CLI prints the stack events, so match the first failed resource's reason there.
Credentials and roles
Message (numbers and names as <n>) | Cause → fix | Check |
|---|---|---|
Could not assume role in target account using <credentials> <error>. Please make sure that this role exists in the account. If it doesn't exist, (re)-bootstrap the environment with the right '--trust', using the latest version of the CDK CLI. | Either the role (cdk-<q>-deploy-role-<account>-<region> or a publishing or lookup role) doesn't exist, or the target doesn't trust your account. Bootstrap the target with --trust <your-account> --cloudformation-execution-policies <arn>, and include every previously trusted account. Also make sure your own policy allows sts:AssumeRole on arn:aws:iam::<target>:role/cdk-<q>-*, that no SCP blocks it, and that the qualifier matches. The embedded <error> is the STS message (reference/sts/errors.md) | aws iam get-role --role-name cdk-<q>-deploy-role-<account>-<region> in the target account → AssumeRolePolicyDocument |
<credentials> could not be used to assume '<role-arn>', but are for the right account. Proceeding anyway. (warning) | Same account, but the assume failed: usually your policy lacks sts:AssumeRole on the cdk-* roles. The CLI carries on with your own credentials, so later steps fail if those lack CloudFormation, S3 or service rights. Grant the assume (patterns/github-actions-to-cdk-deploy.md) | aws sts assume-role --role-arn <role-arn> --role-session-name t with the same credentials |
Need to perform AWS calls for account <n>, but the current credentials are for <n> | The stack's env.account differs from your credentials' account and no role bridges them. Use a profile for the right account, or bootstrap the target with --trust | aws sts get-caller-identity --query Account vs the stack's env.account |
Need to perform AWS calls for account <n>, but no credentials have been configured | No credentials found. Run aws sso login --profile <p> and pass --profile <p> (guides/iam/local-credentials.md) | aws sts get-caller-identity --profile <p> |
Assuming role failed: ExpiredToken | The base session expired. Refresh the SSO login or the CI token | aws sts get-caller-identity fails with the same error |
forbidden: null | The deploying role can't write to the staging bucket, which is used for assets and for templates over about 50 KB. It needs s3:* on that bucket: normally through the file-publishing role. Check the bucket policy and any SCP | aws s3api get-bucket-policy --bucket cdk-<q>-assets-<account>-<region>; cdk deploy -v shows which role published |
Bootstrap missing or outdated
| Message | Cause → fix | Check | ||
|---|---|---|---|---|
SSM parameter /cdk-bootstrap/<q>/version not found in <env>. Has the environment been bootstrapped? Please run 'cdk bootstrap' … | That account and Region aren't bootstrapped, or the app uses a different qualifier or Region. Run cdk bootstrap aws://<account>/<region>, or align the synthesizer's qualifier | aws ssm get-parameter --name /cdk-bootstrap/<q>/version --region <r> | ||
This CDK deployment requires bootstrap stack version '<n>', found '<n>' in <env>. Please run 'cdk bootstrap'. / Bootstrap stack version '<n>' is required, found version '<n>'… | The bootstrap template is older than this app needs. Re-run cdk bootstrap with a current CLI. It is safe and upgrades in place, but keep your --trust and policy options (earlier parameter values are reused by default) | Same call: Parameter.Value is the installed version | ||
NoSuchBucket | Not bootstrapped, or the bucket was deleted. Don't delete and recreate CDKToolkit: re-run cdk bootstrap | aws cloudformation describe-stacks --stack-name CDKToolkit --query 'Stacks[0].Outputs' → BucketName, then aws s3api head-bucket --bucket <name> | ||
Template too large to deploy ("cdk bootstrap" is required) | Without a bootstrap, only stacks with no assets and templates under 51,200 bytes can deploy. Bootstrap | Same SSM call: ParameterNotFound means not bootstrapped | ||
| `CREATE_FAILED \ | AWS::S3::Bucket \ | <BucketName> already exists` during bootstrap | The generated name (cdk-<q>-assets-<account>-<region>) is taken. If it's yours and unused, delete it. If it belongs to an existing CDKToolkit in that Region, you are already bootstrapped. If another account owns it, use --qualifier <new> or --bootstrap-bucket-name <name>, and match it in DefaultStackSynthesizer | aws s3api head-bucket --bucket cdk-<q>-assets-<account>-<region>: 403 means another account owns it, 200 yours |
Synth and app
| Message | Cause → fix | Check |
|---|---|---|
--app is required either in command-line, in cdk.json or in ~/.cdk.json | You're not in the project root (where cdk.json lives). cd there, or pass --app "npx ts-node bin/app.ts" | ls cdk.json in the current directory |
| CLI reports a mismatch with the Construct Library after an upgrade | The CLI must be at least the aws-cdk-lib version. Use the project-local CLI (npx aws-cdk …) or npm update -g aws-cdk. The newest 2.x CLI supports any 1.x and 2.x library | npx cdk --version vs npm ls aws-cdk-lib |
Number of resources in stack '<path>': <n> is greater than allowed maximum of <n>: <counts> (info note Number of resources: <n> is approaching allowed maximum of <n> before it) | CloudFormation's per-stack resource limit (500 when the guide was written; not listed as adjustable). High-level constructs create 1–5 resources each, and serverless APIs 5–8 per endpoint. Split stacks or use NestedStack. The guide's maxResources stack property isn't in aws-cdk-lib 2.273.0's types; the limit there comes from context @aws-cdk/core:stackResourceLimit | Count Resources in cdk.out/<stack>.template.json |
| Asked for 3 AZs, got 2 | The stack is environment-agnostic. Set env: { account, region } or override availabilityZones | env in bin/app.ts; cdk synth shows the AZ list |
Deploy and destroy
| Message | Cause → fix | Check |
|---|---|---|
The stack named <name> is in a failed state. You may need to delete it from the AWS console : <status> | Usually ROLLBACK_COMPLETE after a failed first create, which can only be deleted. Delete it (aws cloudformation delete-stack --stack-name <name> or the console), fix, and redeploy. For other statuses, see guides/cloudformation/fix-failed-stack.md | aws cloudformation describe-stacks --stack-name <s> --query 'Stacks[0].StackStatus' |
<stack> (no changes) | Nothing to deploy. --force deploys anyway | cdk diff |
A stack left failed and paused after --no-rollback | Fix and redeploy, or run cdk rollback. Deployments that replace resources always fail under --no-rollback | describe-stacks → StackStatus (UPDATE_FAILED, CREATE_FAILED) |
Bucket or table survives cdk destroy, then the next deploy fails with already exists | Data resources default to RemovalPolicy.RETAIN. Delete the orphan by hand, or for disposable environments set removalPolicy: RemovalPolicy.DESTROY (and autoDeleteObjects: true on buckets that hold objects) | aws s3api head-bucket / aws dynamodb describe-table on the physical name |
When none of these fits
Run the command again with --verbose to see which role and SDK call failed (UNVERIFIED flag behaviour). Then split the problem. If it fails before any stack event, it's credentials or bootstrap (reference/cdk/bootstrap-roles-and-trust.md). If stack events appear, it's CloudFormation (reference/cloudformation/errors.md). If synth fails, it's the app (guides/cdk/write-stacks-in-typescript.md). Check CloudTrail for the denied AssumeRole (guides/cloudtrail/find-who-did-what.md).