Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

AWS CDK cannot find module '@aws-cdk/aws-ec2' (or another @aws-cdk/aws-* package)

ErrorCannot find module '@aws-cdk/aws-ec2'

Short answer

CDK v2 no longer ships one npm package per service. Stable modules such as EC2 live inside aws-cdk-lib, and Construct comes from the constructs package. Change the import to aws-cdk-lib, drop the old @aws-cdk/aws-* entries, run npm install. Only experimental modules keep separate -alpha packages.

  • Applies to AWS CDK v2, Node.js 22, TypeScript 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    See which CDK major version the project really uses, and which CDK packages it lists. A project written for v1 copy-pasted into v2, or the other way round, is the usual start of this error.

    grep -n "aws-cdk" package.json
    npx cdk --version
  2. 2Match what you see, then jump to its fix

    1. 1Cannot find module '@aws-cdk/aws-ec2' on a project that has aws-cdk-lib installedThe code still imports v1 service packagesFix
    2. 2Imports are already v2 style, but the module is still not found after a fresh clone or a CI runpackage.json still lists the v1 packages, or lacks aws-cdk-lib and constructsFix
    3. 3Cannot find module '@aws-cdk/aws-<service>-alpha' or an L2 construct that is not in aws-cdk-libThe module you want is an experimental -alpha packageFix

What does the error look like?

  • Cannot find module '@aws-cdk/aws-ec2'

Cause 1 of 3

The code still imports v1 service packages

1Check

In v2 the stable parts of the Construct Library, including the core library, are consolidated into the single package aws-cdk-lib, so the separate @aws-cdk/aws-ec2 package is not there to find. Search the code for the old names.

grep -rn "@aws-cdk/" bin lib test

2Fix

Import core types such as App and Stack from aws-cdk-lib, service modules as namespaces of aws-cdk-lib, and Construct from the constructs package.

import { Construct } from 'constructs';
import { App, Stack } from 'aws-cdk-lib';
import { aws_ec2 as ec2 } from 'aws-cdk-lib';

3Verify

The TypeScript build no longer reports the missing module.

npm run build

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 3

package.json still lists the v1 packages, or lacks aws-cdk-lib and constructs

1Check

The migration guide says to remove the dependencies on the v1 individual stable modules and keep aws-cdk-lib and constructs. If those two are missing from package.json, nothing installs them.

grep -n "aws-cdk\|constructs" package.json

2Fix

Edit dependencies so they contain aws-cdk-lib and constructs (and no @aws-cdk/aws-* stable packages), then install.

{
  "dependencies": {
    "aws-cdk-lib": "^2.0.0",
    "constructs": "^10.0.0"
  }
}

3Verify

Install, then build.

npm install
npm run build

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 3

The module you want is an experimental -alpha package

1Check

Modules whose higher-level constructs are still being developed are not in aws-cdk-lib. They are separate packages named @aws-cdk/<service>-alpha, where the service name has an aws- prefix, and they are not installed by default.

npm ls | grep alpha

2Fix

Install the alpha package by its exact name. The CDK guide says to pin exact versions of alpha modules, with no ^ or ~, because their APIs may change.

npm install @aws-cdk/aws-codestar-alpha

3Verify

The import resolves and the build passes.

npm run build

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Check whether a tutorial or older snippet targets CDK v1 before pasting it into a v2 project.
  • Pin alpha modules to the exact version that matches your aws-cdk-lib release.
  • Run npm ci in CI so the lock file decides what installs.
  • If you maintain both v1 and v2 apps, use npx aws-cdk@1.x or npx aws-cdk@2.x instead of a single global toolkit.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.