❗ NOTICE (aws-cdk-lib): npm ci fails with invalid lock file on versions 2.254.0 through 2.256.0 #37949

Status

Completed

What is the issue?

A regression was introduced in aws-cdk-lib versions 2.254.0 through 2.256.0 that causes npm ci to fail with lock file validation errors.

In aws/aws-cdk#37726 (introduced in v2.252.0), a script was added to strip nested dependencies of bundled dependencies to work around an NPM bug where if a package is used as a bundled dependency at multiple levels in a dependency tree, the containing package cannot be itself used as a bundled dependency. However, this script incorrectly stripped nested dependencies that existed due to version conflicts (not just bundling). The version conflicts caused npm ci to fail after aws/aws-cdk#37774 (introduced in v2.254.0) updated the @aws-cdk/cloud-assembly-api to its latest version.

This caused npm ci to detect a mismatch between the declared dependency ranges and the actually bundled versions, resulting in lock file validation failures.

Error message

v2.254.0 / v2.255.0:
code EUSAGE
npm ci can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
Missing: jsonschema@1.4.1 from lock file

v2.256.0:
code EUSAGE
`npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
Invalid: lock file's semver@7.7.4 does not satisfy semver@7.8.0

What is the impact?

Any build process or CI/CD pipeline that uses npm ci will fail when using aws-cdk-lib versions 2.254.0, 2.255.0, or 2.256.0.

Workaround

We recommend updating to the latest unaffected version: v2.256.1 which includes a fix for the issue.

Option 1: Pin to the last unaffected version:

{
  "dependencies": {
    "aws-cdk-lib": "2.253.1"
  }
}

Option 2: Regenerate your lock file after installing:

npm install --package-lock-only

After this, npm ci will succeed.

Who is affected?

All users of aws-cdk-lib versions 2.254.0, 2.255.0, or 2.256.0 whose build process relies on npm ci for clean installs.

How do I resolve this?

Upgrade to aws-cdk-lib version v2.256.1.

The fix has been merged in two parts:

1. aws/aws-cdk-cli#1475 — Removed bundled dependencies from @aws-cdk/cloud-assembly-api in the CLI repo (since it's not a jsii package and doesn't need them bundled), eliminating the nested-in-nested dependency problem that originally required the stripping script.
2. aws/aws-cdk#37943 — Removed the dependency-stripping script from aws-cdk-lib that was incorrectly stripping nested dependencies needed for version conflict resolution.

Related issues

• (aws-cdk-lib): npm ci fails with Missing: jsonschema@1.4.1 from lock file in aws-cdk-lib@2.254.0 #37870
• (@aws-cdk/cloud-assembly-api): (missing bundleDependencies for jsonschema/semver) #37929
• (aws-cdk-lib): Bundled cloud-assembly-api in 2.254.0+ declares dependencies that don't match what cdk ships, breaking npm ci #37944