AWS CDK Toolkit CLI

Common errors

• Error: This CDK application is not supported in the current Node.js version.

  cause The installed Node.js version is below the minimum requirement for AWS CDK v2.
  fix Upgrade 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.

  cause The `cdk` command was executed outside a CDK project root, or the `cdk.json` file is missing/misconfigured.
  fix Navigate 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.

  cause AWS authentication credentials are not configured in your environment or the default region is not set.
  fix Configure 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:...

  cause The IAM user or role performing the `cdk deploy` command lacks the necessary permissions to create, update, or delete the specified AWS resources.
  fix Grant 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'.

  cause The required CDK Toolkit CloudFormation stack has not been deployed to the target AWS account and region.
  fix Run `cdk bootstrap aws://ACCOUNT-ID/REGION` once per account and region to set up the necessary resources for CDK deployments.

Warnings

• breaking AWS 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.
  Fix: Migrate 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.
• breaking The 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.
  Fix: Upgrade your Node.js runtime to an actively supported LTS version (e.g., v18, v20, or v22) in your development environment and CI/CD pipelines.
• gotcha The 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.
  Fix: Run `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.
• gotcha The `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.
  Fix: Regularly 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.
• gotcha CDK 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.
  Fix: Review 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.

Install

• npm install aws-cdk npm
• yarn add aws-cdk yarn
• pnpm add aws-cdk pnpm

Imports

• App
  wrong:

  import { App } from 'aws-cdk';

  correct:

  import { App } from 'aws-cdk-lib';

  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
  wrong:

  import { Stack } from '@aws-cdk/core';

  correct:

  import { Stack } from 'aws-cdk-lib';

  In CDK v2, the `Stack` construct, along with most stable AWS Construct Library modules, is consolidated into the single `aws-cdk-lib` package.
• Bucket
  wrong:

  import { Bucket } from '@aws-cdk/aws-s3';

  correct:

  import * as s3 from 'aws-cdk-lib/aws-s3';
  // OR
  import { Bucket } from 'aws-cdk-lib/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.

Quickstart

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' };
// }