localstack / localstack/aws-cdk-local

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

Open
#126 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.