skip to content

In Node.js, why does `require('my-package/lib/helpers')` throw `ERR_PACKAGE_PATH_NOT_EXPORTED` after the package adds an `exports` map in a minor release?

level: middleimportance: should knowfreq 45%

answer

  1. exports is a whitelist
  2. exports beats main
  3. keys match exactly, no probing
  4. even package.json gets hidden

basics

~10 s

Once a package defines exports, Node resolves only the subpaths that map lists, with no extension or index probing. './lib/helpers' is not a key, so resolution throws ERR_PACKAGE_PATH_NOT_EXPORTED even though the file still exists.

solid answer

~40 s

An `"exports"` field turns a package's folder into a sealed surface. When Node resolves `my-package/lib/helpers` by name, it finds the package's `package.json`, sees `"exports"`, and matches the subpath `./lib/helpers` against its keys and patterns only. `"main"` is ignored, and CommonJS extension probing does not apply. No key matches, so it throws `ERR_PACKAGE_PATH_NOT_EXPORTED` with the message `Package subpath './lib/helpers' is not defined by "exports"`. That is why Node's packages documentation calls introducing `"exports"` likely a breaking change. As a consumer, switch to an exported entry point or pin the previous version while the maintainer decides. A maintainer can restore old paths by listing them, including extension variants and `./package.json`, or with a pattern such as `"./lib/*": "./lib/*.js"`.

code

console · 2 lines
console
$ node -e "require('my-package/lib/helpers')"
Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/helpers' is not defined by "exports" in /app/node_modules/my-package/package.json

go deeper

for a junior

Recall that once a package has an exports field, only the subpaths it lists can be loaded by package name, and anything else throws ERR_PACKAGE_PATH_NOT_EXPORTED.

for a middle

Explain the mechanics: exports beats main, keys match literally, patterns substitute one star, null refuses a path, and package.json itself is hidden unless listed.

for a senior

Show how you would triage it in production: read the installed exports map, choose between the public entry, a version pin or an upstream fix, and avoid absolute-path workarounds.

for a principal

Treat deep imports into dependencies as a team risk: decide whether to forbid them, guard required paths with resolve checks in tests, and how strictly to pin.

## What the exports field changes A package's `package.json` can name its entry points in two fields. **`"main"`** names a single entry for the bare package name and leaves every file in the folder reachable by path. **`"exports"`** names every public entry and hides the rest. When both exist, Node uses `"exports"` and ignores `"main"` for anything loaded through the package's name. Before the release, `require('my-package/lib/helpers')` worked through the plain `node_modules` rules: Node found the folder, then tried `lib/helpers`, `lib/helpers.js` and so on. After the release, the same call takes a different path: 1. Node finds `node_modules/my-package/package.json` and sees an `"exports"` field. 2. It turns the request into the subpath `./lib/helpers`. 3. It looks for an exact key `"./lib/helpers"`, then for a pattern key with one `*` whose prefix and suffix fit. 4. Nothing matches, so it throws `ERR_PACKAGE_PATH_NOT_EXPORTED`. It never falls back to the file on disk. The message for a CommonJS caller reads `Package subpath './lib/helpers' is not defined by "exports" in /app/node_modules/my-package/package.json`. An ES module caller gets the same text plus `imported from` and the importing file. ## Rules that make old paths disappear - **Keys are literal.** `"./lib/helpers.js"` does not match `./lib/helpers`; the extension is part of the key, and nothing is probed. - **Folders need their own key.** `require('my-package/lib')` used to find `lib/index.js`; under `"exports"` it needs a `"./lib"` key. - **`package.json` is hidden too.** `require('my-package/package.json')`, a common way to read a version, fails unless `"./package.json"` is exported. - **`null` blocks a path.** A key mapped to `null` refuses that subpath even when a broader pattern would allow it. - **The ES module side matches the same keys.** Both loaders run the same exports-matching algorithm; what differs is the set of active conditions. ## What the consumer can do | Option | Effect | Cost | |---|---|---| | Import the public entry | Works across future releases | Code change; the helper may not be public | | Pin the previous minor | Restores the old tree | Freezes fixes until the code changes | | Ask the maintainer to export the path | Fixes it for everyone | Waits on a new release | | Require the absolute file path | Works, since the encapsulation is not strong | Ties the code to the package's internal layout | Node's documentation is explicit that `"exports"` is not strong encapsulation: `require('/abs/path/node_modules/my-package/lib/helpers.js')` still loads the file. That escape hatch is a diagnosis tool, not a fix, because the internal layout can change in any release. ## How a map keeps old paths working Node's packages documentation recommends that a package introducing `"exports"` list every entry point it previously supported, so the change is not breaking: - list each former path with and without its extension (`"./lib/helpers"` and `"./lib/helpers.js"`), or cover a folder with patterns (`"./lib/*": "./lib/*.js"` plus `"./lib/*.js": "./lib/*.js"`); - keep `"./package.json": "./package.json"` if consumers read it; - tighten the map to the real public surface in the next major version. A `*` in a pattern is plain string substitution and can span `/` separators, so `"./lib/*"` also exposes nested files under `lib/`. ## Why a minor release can do this The installed version moved because a range such as `^2.3.0` accepts any later `2.x` release, so a fresh install or a rebuilt container image picks up the new map with no change in your repository. The code did not change; the resolution rules for that package did. That is also why the failure tends to appear in a deploy rather than on a developer machine with an older tree: the two installs disagree about which `package.json` Node reads. ## Diagnosing it quickly Read the `"exports"` field of the installed package first: the error names the exact `package.json`. Then compare the subpath in the message with the keys. `require.resolve('my-package/lib/helpers')` and `import.meta.resolve('my-package/lib/helpers')` reproduce the decision without running any code, which makes them handy in a test that guards the import paths your service depends on.

  • Why does `require('my-package/package.json')` start failing in Node.js after the package adds `exports`?
    Every subpath loaded through the package name goes through the exports map, and `./package.json` is just another subpath. Unless the map has a `"./package.json"` key, Node throws `ERR_PACKAGE_PATH_NOT_EXPORTED`. Packages that expect consumers or tools to read their manifest export it explicitly.
  • In Node.js, does a `"./lib/*": "./lib/*.js"` pattern expose files in nested folders under `lib`?
    Yes. The `*` is plain string substitution and may contain `/`, so `my-package/lib/a/b` maps to `./lib/a/b.js`. To hide a subfolder, add a more specific key mapped to `null`, such as `"./lib/internal/*": null`. Targets may not contain `..` or `node_modules` segments, so a pattern cannot reach outside the package.

  • Node falls back to main when an exports key does not match
  • require still probes .js and index files for exported subpaths
  • exports only restricts import, so require keeps working as before
  • The file must have been deleted from the package
  • exports is strong encapsulation that absolute paths cannot bypass