--- cuppy_hub: aws cuppy_path: reference/cdk/errors.md cuppy_section: docs cuppy_doc: MGG0-0X5M cuppy_doc_uuid: a9a1a546-33aa-42ba-b471-5593da677fad cuppy_permalink: https://cuppy.io/aws/d/MGG0-0X5M cuppy_version: 4 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/aws/docs/reference/cdk/errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: efe1acb5e9202076e161920a70c721b6fdba0848f79f9660a744cf2d4ef81b0b # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # AWS CDK CLI errors **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 ``) | Cause → fix | Check | |---|---|---| | `Could not assume role in target account using . 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--deploy-role--` or a publishing or lookup role) doesn't exist, or the target doesn't trust your account. Bootstrap the target with `--trust --cloudformation-execution-policies `, and include every previously trusted account. Also make sure your **own** policy allows `sts:AssumeRole` on `arn:aws:iam:::role/cdk--*`, that no SCP blocks it, and that the qualifier matches. The embedded `` is the STS message (`reference/sts/errors.md`) | `aws iam get-role --role-name cdk--deploy-role--` in the target account → `AssumeRolePolicyDocument` | | ` could not be used to assume '', 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-session-name t` with the same credentials | | `Need to perform AWS calls for account , but the current credentials are for ` | 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 , but no credentials have been configured` | No credentials found. Run `aws sso login --profile

` and pass `--profile

` (`guides/iam/local-credentials.md`) | `aws sts get-caller-identity --profile

` | | `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--assets--`; `cdk deploy -v` shows which role published | ## Bootstrap missing or outdated | Message | Cause → fix | Check | |---|---|---| | `SSM parameter /cdk-bootstrap//version not found in . 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:///`, or align the synthesizer's qualifier | `aws ssm get-parameter --name /cdk-bootstrap//version --region ` | | `This CDK deployment requires bootstrap stack version '', found '' in . Please run 'cdk bootstrap'.` / `Bootstrap stack version '' is required, found version ''…` | 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 ` | | `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 \| already exists` during bootstrap | The generated name (`cdk--assets--`) 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 ` or `--bootstrap-bucket-name `, and match it in `DefaultStackSynthesizer` | `aws s3api head-bucket --bucket cdk--assets--`: 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 '': is greater than allowed maximum of : ` (info note `Number of resources: is approaching allowed maximum of ` 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/.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 is in a failed state. You may need to delete it from the AWS console : ` | Usually `ROLLBACK_COMPLETE` after a failed first create, which can only be deleted. Delete it (`aws cloudformation delete-stack --stack-name ` or the console), fix, and redeploy. For other statuses, see `guides/cloudformation/fix-failed-stack.md` | `aws cloudformation describe-stacks --stack-name --query 'Stacks[0].StackStatus'` | | ` (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`). --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.