cdklocal broken with aws-cdk >= 2.1114.0 (legacy exports removed)

[jamestroutman]

Description

cdklocal fails with ERR_PACKAGE_PATH_NOT_EXPORTED when used with aws-cdk@2.1114.0 or later. AWS removed legacy exports from the aws-cdk package starting in 2.1114.0 (see aws/aws-cdk-cli#310).

Error

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/cdk-toolkit' is not defined by "exports" in node_modules/aws-cdk/package.json

Root Cause

In aws-cdk@2.1113.0, the package exported 35 subpaths (all routing through ./lib/legacy-exports.js). Starting with 2.1114.0, exports were stripped to just 4:

{
  "./package.json": "./package.json",
  "./build-info.json": "./build-info.json",
  "./bin/cdk": "./bin/cdk",
  "./lib/api/bootstrap/bootstrap-template.yaml": "./lib/api/bootstrap/bootstrap-template.yaml"
}

This breaks the isEsbuildBundle() check in cdklocal (line ~373), which tries require("aws-cdk/lib/util/directories"). Since that subpath is no longer exported, the function returns false, causing cdklocal to fall through to the patchPre_2_14() code path. That path makes several deep imports (aws-cdk/lib/cdk-toolkit, aws-cdk/lib/api/aws-auth/sdk, etc.) that also aren't exported, resulting in the crash.

Affected Versions

• Broken: aws-cdk >= 2.1114.0 with aws-cdk-local 2.x and 3.x (tested with 2.19.2 and 3.0.4)
• Last working: aws-cdk@2.1113.0

Expected Behavior

cdklocal should work with current aws-cdk versions. The AWS CDK team recommends migrating to @aws-cdk/toolkit-lib for programmatic access.

Workaround

Pin aws-cdk to 2.1113.0 (the last version with legacy exports).

Environment

• Node.js: v22.22.1
• aws-cdk-local: 2.19.2 / 3.0.4
• aws-cdk: 2.1118.0
• LocalStack: 2026.3.0