node error ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath not defined by exports after node 22 upgrade

TL;DR

Change the import to one of the package's exported entry points (check its exports map), or upgrade or pin the package to a version whose exports include the subpath. Node throws because the package's exports field does not list the deep subpath you are importing, and Node 22 resolves it strictly. Importing through the public surface fixes it.

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/internal' is not defined by "exports" in /path/to/node_modules/some-package/package.json

Steps

1. Read the error: note the package name and the subpath. Open that package's package.json in node_modules and read its exports field. Expected: the subpath you import is absent from the map.

2. Check whether the package documents a public import for what you need, and switch your import to it. Expected: your import matches an entry in exports.

3. If no public entry exists, upgrade the package (newer releases often widen exports), or replace the deep import with the package's main entry plus your own logic. Expected: no import reaches into the package's internals.

4. As a last resort, pin the older package version whose layout worked, and report the missing export upstream. Do not hand-patch node_modules; it will not survive reinstalls. Expected: a reproducible, documented workaround instead of a local hack.

5. Restart the app. Expected: no ERRPACKAGEPATHNOTEXPORTED, and the app boots.

Use this when

• Node 22 upgrade with deep subpath imports throwing at startup
• The error names a package plus a subpath
• A dependency update added an exports field that omits the path you relied on
• The failure is at import/require time, not at runtime

Not for this skill when

• The error is ERRMODULENOT_FOUND (the package itself is missing, different fix)
• Only a bundler complains about exports (bundler resolution, different topic)
• The subpath is in a package you own (add the export to your own package.json instead)
• The import worked because there was no exports field at all and you control the package (same: add exports)

Variant phrasings

• node 22 package subpath is not defined by exports
• ERRPACKAGEPATHNOTEXPORTED after upgrade
• package exports deep import node error
• node error package subpath exports map

Why it happens

The exports field is an allowlist: anything not listed is private, and Node enforces it for both import and require. Code that deep-imported internal files worked only while the package had no exports field (or while a looser resolver was in play). A dependency update adding exports, combined with Node 22's stricter default module handling (require of ESM is now on by default, which can change which export conditions resolve), turns the previously-working deep import into a hard error.

Edge cases

• require() and import can hit different export conditions. A subpath may be exported for one and not the other.
• Node 22 enables require(esm) by default. A package that only exports ESM may now load where it previously threw a different error, shifting the failure to the subpath check.
• TypeScript's moduleResolution: bundler is lenient about exports; node16/nodenext match Node strictly. Align them to catch this at typecheck time.
• If you own the package, add the subpath to exports rather than telling consumers to deep-import around it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7RgQXEAkNMLeHYEQLSdecA