Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
App
✓ import { App } from 'aws-cdk-lib';
✗ import { App } from 'aws-cdk';
The `aws-cdk` package is the CLI. For programmatic use in a CDK application, core constructs like `App` are imported from `aws-cdk-lib` (CDK v2).
Stack
✓ import { Stack } from 'aws-cdk-lib';
✗ import { Stack } from '@aws-cdk/core';
In CDK v2, the `Stack` construct, along with most stable AWS Construct Library modules, is consolidated into the single `aws-cdk-lib` package.
Bucket
✓ import * as s3 from 'aws-cdk-lib/aws-s3';
// OR
import { Bucket } from 'aws-cdk-lib/aws-s3';
✗ import { Bucket } from '@aws-cdk/aws-s3';
AWS service-specific constructs like `Bucket` (for S3) are imported from sub-paths of `aws-cdk-lib` in CDK v2. In v1, they were separate `@aws-cdk/aws-s3` packages.
This TypeScript code defines a basic AWS CDK application with an S3 bucket and a Node.js Lambda function. The `aws-cdk` CLI would then be used to synthesize (`cdk synth`) and deploy (`cdk deploy`) this infrastructure to an AWS account after `cdk init` and `cdk bootstrap`.
import { App, Stack } from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
const app = new App();
const myStack = new Stack(app, 'MySimpleCdkStack', {
env: {
account: process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEFAULT_REGION,
},
});
new s3.Bucket(myStack, 'MyBucket', {
versioned: true,
// Ensure bucket name is unique
bucketName: `my-unique-cdk-bucket-${myStack.account?.toLowerCase()}-${myStack.region?.toLowerCase()}`
});
new NodejsFunction(myStack, 'MyLambdaFunction', {
runtime: lambda.Runtime.NODEJS_18_X,
entry: 'src/handler.ts',
handler: 'handler',
environment: {
MESSAGE: 'Hello from CDK Lambda!',
},
});
// Dummy handler file for NodejsFunction (src/handler.ts)
// export async function handler(event: any) {
// console.log('Received event:', JSON.stringify(event, null, 2));
// return { statusCode: 200, body: process.env.MESSAGE || 'No message' };
// }
cdk --version
Debug
Known issues
breakingAWS CDK v1 reached end-of-support on June 1, 2023. Continuing to use v1 exposes projects to security vulnerabilities and unaddressed bugs, and may result in incompatibility with new AWS services and features.fixMigrate to AWS CDK v2. This involves updating package dependencies to `aws-cdk-lib`, changing import statements, and re-bootstrapping AWS accounts. Tools like `awscdk-v1-stack-finder` can assist.
affects: <2.0.0
breakingThe AWS CDK CLI requires Node.js v18 or newer. Support for Node.js 14.x and 16.x officially ended on May 30, 2025. Using unsupported Node.js versions may lead to build failures, unexpected behavior, and lack of support.fixUpgrade your Node.js runtime to an actively supported LTS version (e.g., v18, v20, or v22) in your development environment and CI/CD pipelines.
affects: >=2.0.0 (specifically for Node.js <18.0.0)
gotchaThe AWS account and region must be 'bootstrapped' with a CDK Toolkit stack before the first deployment using `cdk deploy` in that environment. This stack manages assets and deployment permissions.fixRun `cdk bootstrap aws://ACCOUNT-ID/REGION` for each AWS account and region where you plan to deploy CDK applications. For existing V1 bootstrapped accounts, re-bootstrap them for V2.
affects: >=2.0.0
gotchaThe `aws-cdk` CLI and `aws-cdk-lib` (Construct Library) now have independent release cadences, meaning their version numbers may diverge. While the CLI generally supports older library versions, always ensure your CLI is up-to-date.fixRegularly update your `aws-cdk` CLI (`npm update -g aws-cdk` or `npm install -g aws-cdk@latest`) at least as often as you update your `aws-cdk-lib` dependencies to maintain compatibility.
affects: >=2.1000.0 (for CLI), >=2.175.0 (for Construct Library)
gotchaCDK deployments require specific IAM permissions for the deploying identity to interact with CloudFormation and provision resources. Default permissions, especially after bootstrapping, might not be sufficient for all resource types.fixReview and apply the least-privilege IAM policies to your deployment role. Refer to the AWS CDK documentation for required permissions, especially for asset publishing and SSM parameter access if using the modern bootstrap stack.
affects: >=2.0.0
Errors
Common errors & fixes
Error: This CDK application is not supported in the current Node.js version.
The installed Node.js version is below the minimum requirement for AWS CDK v2.
fixUpgrade your Node.js environment to version 18 or higher. Use `nvm install 18 && nvm use 18` or your preferred Node.js version manager.
No stacks found in the app. Make sure you are in a CDK app directory.
The `cdk` command was executed outside a CDK project root, or the `cdk.json` file is missing/misconfigured.
fixNavigate to the root directory of your CDK project (where `cdk.json` is located) or verify that `cdk.json` correctly points to your application entry point.
The 'default' credential provider chain failed to retrieve credentials. Regions or sources not set.
AWS authentication credentials are not configured in your environment or the default region is not set.
fixConfigure your AWS CLI with valid credentials (`aws configure`) and ensure the `AWS_REGION` environment variable or `--region` flag is specified.
CloudFormation deployments failed: User: arn:aws:iam::ACCOUNT-ID:user/username is not authorized to perform:...
The IAM user or role performing the `cdk deploy` command lacks the necessary permissions to create, update, or delete the specified AWS resources.
fixGrant the required IAM permissions to the deploying entity. Start with policies like `AdministratorAccess` for testing, then refine to least privilege as you understand the resource requirements.
Stack 'CDKToolkit' is not bootstrapped in account 'ACCOUNT-ID' and region 'REGION'.
The required CDK Toolkit CloudFormation stack has not been deployed to the target AWS account and region.
fixRun `cdk bootstrap aws://ACCOUNT-ID/REGION` once per account and region to set up the necessary resources for CDK deployments.
Audit
Dependencies
No dependency data recorded yet.