Node "ERR_PACKAGE_PATH_NOT_EXPORTED: subpath not defined by exports" in CI

The package you imported declares an exports field, which is an encapsulation boundary. Any path not listed in exports is private, so a deep import into internal files is rejected.

What this error means

A deep import such as import x from "pkg/lib/internal.js" fails with "Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath ./lib/internal.js is not defined by exports".

node:internal/modules/esm/resolve:... Error [ERR_PACKAGE_PATH_NOT_EXPORTED]:
Package subpath './lib/internal.js' is not defined by "exports" in
/app/node_modules/some-pkg/package.json

Common causes

Reaching into a path the package keeps private

The package added an exports map; only listed subpaths are importable, and your deep path is not one of them.

An old deep-import pattern after an upgrade

Code that imported internals worked before the package adopted exports; the upgrade now enforces the boundary.

How to fix it

Import only the public entry points

1. Open the package package.json and read its exports map.
2. Switch to a path the package actually exports (often the root or a documented subpath).
3. Re-run once imports use only public entries.

// instead of deep internals:
import { thing } from 'some-pkg';

Request a public subpath upstream

If you genuinely need the internal file, ask the maintainer to add it to exports, or vendor the needed code.

How to prevent it

• Depend only on documented public entry points.
• Read the exports map before deep-importing a dependency.
• Avoid reaching into node_modules internals that may change.

Related guides