aws-cdk

$27

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 prod

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

Troubleshooting

Error

Cause → Fix

DeployFailed / DeploymentError

CDK error is not root cause. Check CFN events: aws cloudformation describe-stack-events --stack-name $STACK --query "StackEvents[?contains(ResourceStatus,'FAILED')]". 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 SDK v3 migration, Python deps not bundled. Details

API Gateway multi-stage conflicts

Set deploy: false on RestApi, create Deployment and Stage explicitly. 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 bootstrap

• grant*() for inter-resource IAM

• cdk-nag + --strict in CI

• Stateful resources in own stack with terminationProtection: true

• Commit cdk.context.json