localstack / localstack/aws-cdk-local
cdklocal broken with aws-cdk >= 2.1114.0 (legacy exports removed)
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 305
- Forks
- 18
- PR merge metrics
- No merged PRs in 30d
Description
## 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](https://github.com/aws/aws-cdk-cli/issues/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:
```json
{
"./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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the isEsbuildBundle() check around line 373 and trace how its result selects the patchPre_2_14() path. Review the deep imports named in the issue and the AWS recommendation to use @aws-cdk/toolkit-lib. Done means cdklocal works with aws-cdk 2.1114.0 and later without requiring legacy exports.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, javascript, node.js
- Domain
- cli, cloud
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100