AWS CDK
Overview
Domain expertise for CDK construct authoring, deployment workflows, compliance, drift, importing resources, safe refactoring, and troubleshooting CDK CLI / CloudFormation errors.
When NOT to use: Raw CloudFormation YAML/JSON. SAM. Terraform/Pulumi. CI/CD beyond CDK Pipelines. Use builtin knowledge or specialized skills for these.
Critical Warnings
Deadly embrace: Removing a cross-stack reference deadlocks deployment (Export ... cannot be deleted as it is in use by ...). Preferred fix: weaken the reference first — CrossStackReferences.of($RESOURCE).produce(ReferenceStrength.BOTH) then WEAK, then remove (three deploys). Legacy fallback: two-deploy this.exportValue() recipe. See troubleshooting-deployment.
Construct ID changes cause replacement: Renaming/moving a construct changes its logical ID → CloudFormation replaces the resource (data loss for stateful resources). Always cdk diff before deploy. See refactor-and-prevent-replacement.
UPDATE_ROLLBACK_FAILED: Stack is stuck. Fix with cdk rollback $STACK or cdk rollback $STACK --orphan <LogicalId>. Express mode stacks are the exception — they cannot be rolled back at all. See troubleshooting-deployment.
Hotswap and express mode are development-only: --hotswap / --hotswap-fallback bypass CloudFormation and create drift on purpose; --express reports success before resources stabilize and disables automatic rollback. You MUST NOT use either in production. A failed --express deployment cannot be rolled back — recover by rolling forward with another --express deploy. See fast-deployments.
Non-empty S3 buckets persist after destroy: You MUST set both removalPolicy: DESTROY and autoDeleteObjects: true. Versioned buckets are worse — delete markers persist even after apparent deletion.
Common Workflows
| Task |
Quick Command |
Details |
| Bootstrap |
cdk bootstrap aws://$ACCOUNT/$REGION |
bootstrap-and-project-setup |
| New TS project |
cdk init app --language typescript — use tsx, eslint-plugin-awscdk |
bootstrap-and-project-setup |
| New Python project |
cdk init app --language python — pin deps, use virtualenv |
bootstrap-and-project-setup |
| Deploy |
cdk synth --strict → cdk diff → cdk deploy |
Always diff before deploy to production |
| Fast dev iteration |
cdk deploy --hotswap-fallback, cdk watch, or cdk deploy --express — dev only, never production |
fast-deployments |
| cdk-nag |
Aspects.of(app).add(new AwsSolutionsChecks()) |
compliance-and-drift |
| Drift |
cdk drift $STACK (use --fail in CI) |
compliance-and-drift |
| Import resource |
cdk import (interactive or --resource-mapping for CI), cdk deploy --import-existing-resources |
import-and-migrate |
| Refactor safely |
cdk refactor --unstable=refactor — no property changes in same deploy |
refactor-and-prevent-replacement |
Fast Deployments — Hotswap vs Express (dev only)
Both trade safety for speed and you MUST NOT use either in production.
Choosing between them: Use --hotswap / --hotswap-fallback for the fastest loop when you work mostly with hotswappable resources and drift does not matter. Use --express when drift is unacceptable, or your resources are not hotswappable.
Recovery workflows (hotswap drift via --revert-drift, rolling a failed --express deploy forward), the hotswappable-resource rules, and IAM/monitoring enforcement of the prod prohibition are all in the full guide: fast-deployments.
Troubleshooting
| Error |
Cause → Fix |
| DeployFailed / DeploymentError |
CDK error isn't the root cause. cdk deploy $STACK --verbose, then cdk --unstable=diagnose diagnose $STACK (CLI ≥ 2.1120.0); else aws cloudformation describe-events --stack-name $STACK --filters FailedEvents=true — the first _FAILED event is the cause. Details |
| NoCredentials / ExpiredToken / AssumeRoleFailed |
aws sts get-caller-identity + cdk doctor. Expired SSO, missing env, missing sts:AssumeRole. Details |
| Asset errors (CannotFindAsset, FailedToBundleAsset, AssetBuildFailed, AssetPublishFailed) |
Path wrong, Docker not running, or bootstrap bucket perms. Use path.join(__dirname, ...). Details |
| AppRequired |
Add "app": "npx tsx bin/my-app.ts" to cdk.json. Details |
| AnnotationErrors |
Fix the underlying issue; suppress with NagSuppressions only as last resort. Details |
| ConcurrentReadLock / ConcurrentWriteLock |
rm -rf cdk.out then re-run. Parallel CI: --output ./cdk.out.$BUILD_ID. Details |
| BootstrapVersionValidation |
Re-bootstrap. Match --qualifier everywhere. Details |
| DependencyCycle |
Extract shared resource into third stack or use SSM for late-binding. Details |
| UnresolvedAccount |
Set explicit env: { account, region } on stack. Commit cdk.context.json. Details |
| NoStacksMatched |
CDK uses logical ID (2nd constructor arg), not CFN name. cdk list to find IDs. Details |
| Cannot find module (synth time) |
Run npx tsc --noEmit, check cdk.json app path matches tsconfig.json outDir, delete stale .js files. Python: activate venv. Details |
| V1 import paths / duplicate aws-cdk-lib |
V1 @aws-cdk/* imports, wrong Construct import, duplicate lib copies in monorepos. Details |
| Lambda Cannot find module (runtime) |
Wrong handler value, missing AWS SDK v3 migration, Python deps not bundled. Details |
| API Gateway multi-stage conflicts |
Set deploy: false on RestApi, create Deployment and Stage explicitly. Details |
Change didn't deploy under --hotswap |
Changes to non-hotswappable resources are silently ignored and only logged — the command still reports success. Read the output; use --hotswap-fallback to force a CloudFormation deployment instead. Details |
Failed --express deploy / can't roll back |
Express mode cannot use the Rollback Stack API, and a standard deploy MUST NOT be used to recover it. Roll forward: fix the cause, then cdk deploy $STACK --express. Details |
| Unexpected drift on a dev stack |
Hotswap and cdk watch create drift by design. Until reverted, the live resources — not CloudFormation's records — are authoritative. Reconcile with cdk deploy $STACK --revert-drift, which uses Drift Aware Changesets to bring live resources in line with the template (updates reality to match desired state; does NOT rewrite CF records to match drifted resources). Details |
Construct Patterns
Prefer L2. Use L1 with Mixins/Facades when L2 lacks a property. Escape hatches: node.defaultChild → addPropertyOverride. See construct-patterns.
Additional Resources
- Search AWS documentation for "CDK Developer Guide", "CDK API Reference" and "CDK Pipelines" respectively
Security Considerations
- OIDC for CI/CD credentials (no static keys)
--custom-permissions-boundary on bootstrapgrant*() for inter-resource IAMcdk-nag + --strict in CI- Stateful resources in own stack with
terminationProtection: true
- Commit
cdk.context.json
1---2name: aws-cdk3description: Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Applies when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.4---5
6# AWS CDK
7
8## Overview
9
10Domain expertise for CDK construct authoring, deployment workflows, compliance, drift, importing resources, safe refactoring, and troubleshooting CDK CLI / CloudFormation errors.
11
12**When NOT to use:** Raw CloudFormation YAML/JSON. SAM. Terraform/Pulumi. CI/CD beyond CDK Pipelines. Use builtin knowledge or specialized skills for these.
13
14## Critical Warnings
15
16**Deadly embrace**: Removing a cross-stack reference deadlocks deployment (`Export ... cannot be deleted as it is in use by ...`). Preferred fix: weaken the reference first — `CrossStackReferences.of($RESOURCE).produce(ReferenceStrength.BOTH)` then `WEAK`, then remove (three deploys). Legacy fallback: two-deploy `this.exportValue()` recipe. See [troubleshooting-deployment](references/troubleshooting-deployment.md).
17
18**Construct ID changes cause replacement**: Renaming/moving a construct changes its logical ID → CloudFormation replaces the resource (data loss for stateful resources). Always `cdk diff` before deploy. See [refactor-and-prevent-replacement](references/refactor-and-prevent-replacement.md).
19
20**UPDATE_ROLLBACK_FAILED**: Stack is stuck. Fix with `cdk rollback $STACK` or `cdk rollback $STACK --orphan <LogicalId>`. Express mode stacks are the exception — they cannot be rolled back at all. See [troubleshooting-deployment](references/troubleshooting-deployment.md).
21
22**Hotswap and express mode are development-only**: `--hotswap` / `--hotswap-fallback` bypass CloudFormation and create drift on purpose; `--express` reports success before resources stabilize and disables automatic rollback. You MUST NOT use either in production. A failed `--express` deployment cannot be rolled back — recover by rolling forward with another `--express` deploy. See [fast-deployments](references/fast-deployments.md).
23
24**Non-empty S3 buckets persist after destroy**: You MUST set both `removalPolicy: DESTROY` and `autoDeleteObjects: true`. Versioned buckets are worse — delete markers persist even after apparent deletion.
25
26## Common Workflows
27
28| Task | Quick Command | Details |
29|------|--------------|---------|
30| Bootstrap | `cdk bootstrap aws://$ACCOUNT/$REGION` | [bootstrap-and-project-setup](references/bootstrap-and-project-setup.md) |
31| New TS project | `cdk init app --language typescript` — use `tsx`, `eslint-plugin-awscdk` | [bootstrap-and-project-setup](references/bootstrap-and-project-setup.md) |
32| New Python project | `cdk init app --language python` — pin deps, use virtualenv | [bootstrap-and-project-setup](references/bootstrap-and-project-setup.md) |
33| Deploy | `cdk synth --strict` → `cdk diff` → `cdk deploy` | Always diff before deploy to production |
34| Fast dev iteration | `cdk deploy --hotswap-fallback`, `cdk watch`, or `cdk deploy --express` — dev only, never production | [fast-deployments](references/fast-deployments.md) |
35| cdk-nag | `Aspects.of(app).add(new AwsSolutionsChecks())` | [compliance-and-drift](references/compliance-and-drift.md) |
36| Drift | `cdk drift $STACK` (use `--fail` in CI) | [compliance-and-drift](references/compliance-and-drift.md) |
37| Import resource | `cdk import` (interactive or `--resource-mapping` for CI), `cdk deploy --import-existing-resources` | [import-and-migrate](references/import-and-migrate.md) |
38| Refactor safely | `cdk refactor --unstable=refactor` — no property changes in same deploy | [refactor-and-prevent-replacement](references/refactor-and-prevent-replacement.md) |
39
40## Fast Deployments — Hotswap vs Express (dev only)
41
42Both trade safety for speed and you MUST NOT use either in production.
43
44**Choosing between them:** Use `--hotswap` / `--hotswap-fallback` for the fastest loop when you work mostly with hotswappable resources and drift does not matter. Use `--express` when drift is unacceptable, or your resources are not hotswappable.
45
46Recovery workflows (hotswap drift via `--revert-drift`, rolling a failed `--express` deploy forward), the hotswappable-resource rules, and IAM/monitoring enforcement of the prod prohibition are all in the full guide: [fast-deployments](references/fast-deployments.md).
47
48## Troubleshooting
49
50| Error | Cause → Fix |
51|-------|------------|
52| **DeployFailed / DeploymentError** | CDK error isn't the root cause. `cdk deploy $STACK --verbose`, then `cdk --unstable=diagnose diagnose $STACK` (CLI ≥ 2.1120.0); else `aws cloudformation describe-events --stack-name $STACK --filters FailedEvents=true` — the first `_FAILED` event is the cause. [Details](references/troubleshooting-deployment.md) |
53| **NoCredentials / ExpiredToken / AssumeRoleFailed** | `aws sts get-caller-identity` + `cdk doctor`. Expired SSO, missing `env`, missing `sts:AssumeRole`. [Details](references/troubleshooting-credentials.md) |
54| **Asset errors** (CannotFindAsset, FailedToBundleAsset, AssetBuildFailed, AssetPublishFailed) | Path wrong, Docker not running, or bootstrap bucket perms. Use `path.join(__dirname, ...)`. [Details](references/troubleshooting-synth.md) |
55| **AppRequired** | Add `"app": "npx tsx bin/my-app.ts"` to `cdk.json`. [Details](references/troubleshooting-synth.md) |
56| **AnnotationErrors** | Fix the underlying issue; suppress with `NagSuppressions` only as last resort. [Details](references/troubleshooting-synth.md) |
57| **ConcurrentReadLock / ConcurrentWriteLock** | `rm -rf cdk.out` then re-run. Parallel CI: `--output ./cdk.out.$BUILD_ID`. [Details](references/troubleshooting-synth.md) |
58| **BootstrapVersionValidation** | Re-bootstrap. Match `--qualifier` everywhere. [Details](references/troubleshooting-credentials.md) |
59| **DependencyCycle** | Extract shared resource into third stack or use SSM for late-binding. [Details](references/troubleshooting-synth.md) |
60| **UnresolvedAccount** | Set explicit `env: { account, region }` on stack. Commit `cdk.context.json`. [Details](references/troubleshooting-credentials.md) |
61| **NoStacksMatched** | CDK uses logical ID (2nd constructor arg), not CFN name. `cdk list` to find IDs. [Details](references/troubleshooting-synth.md) |
62| **Cannot find module** (synth time) | Run `npx tsc --noEmit`, check `cdk.json` app path matches `tsconfig.json` `outDir`, delete stale `.js` files. Python: activate venv. [Details](references/troubleshooting-synth.md) |
63| **V1 import paths / duplicate aws-cdk-lib** | V1 `@aws-cdk/*` imports, wrong `Construct` import, duplicate lib copies in monorepos. [Details](references/v1-to-v2-migration.md) |
64| **Lambda Cannot find module** (runtime) | Wrong handler value, missing AWS SDK v3 migration, Python deps not bundled. [Details](references/troubleshooting-deployment.md) |
65| **API Gateway multi-stage conflicts** | Set `deploy: false` on `RestApi`, create `Deployment` and `Stage` explicitly. [Details](references/troubleshooting-deployment.md) |
66| **Change didn't deploy under `--hotswap`** | Changes to non-hotswappable resources are silently ignored and only logged — the command still reports success. Read the output; use `--hotswap-fallback` to force a CloudFormation deployment instead. [Details](references/fast-deployments.md) |
67| **Failed `--express` deploy / can't roll back** | Express mode cannot use the Rollback Stack API, and a standard deploy MUST NOT be used to recover it. Roll forward: fix the cause, then `cdk deploy $STACK --express`. [Details](references/fast-deployments.md) |
68| **Unexpected drift on a dev stack** | Hotswap and `cdk watch` create drift by design. Until reverted, the live resources — not CloudFormation's records — are authoritative. Reconcile with `cdk deploy $STACK --revert-drift`, which uses Drift Aware Changesets to bring live resources in line with the template (updates reality to match desired state; does NOT rewrite CF records to match drifted resources). [Details](references/fast-deployments.md) |
69
70## Construct Patterns
71
72Prefer L2. Use L1 with Mixins/Facades when L2 lacks a property. Escape hatches: `node.defaultChild` → `addPropertyOverride`. See [construct-patterns](references/construct-patterns.md).
73
74## Additional Resources
75
76- Search AWS documentation for "CDK Developer Guide", "CDK API Reference" and "CDK Pipelines" respectively
77
78## Security Considerations
79
80- OIDC for CI/CD credentials (no static keys)
81- `--custom-permissions-boundary` on bootstrap
82- `grant*()` for inter-resource IAM
83- `cdk-nag` + `--strict` in CI
84- Stateful resources in own stack with `terminationProtection: true`
85- Commit `cdk.context.json`
aws