Error [ERR_PACKAGE_PATH_NOT_EXPORTED]

Exact Error Messages You Will See

Full Error Stack Trace

node:internal/modules/esm/resolve:265
    throw new ERR_PACKAGE_PATH_NOT_EXPORTED(pkgPath, subpath, base);
          ^

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

    at exportsNotExported (node:internal/modules/esm/resolve:265:13)
    at packageExportsResolve (node:internal/modules/esm/resolve:591:13)
    at resolveExports (node:internal/modules/cjs/loader:591:36)
    at Module._findPath (node:internal/modules/cjs/loader:688:31)
    at Module._resolveFilename (node:internal/modules/cjs/loader:1130:27)
    at Object.<anonymous> (/project/index.js:1:1) {
  code: 'ERR_PACKAGE_PATH_NOT_EXPORTED'
}

What is ERR_PACKAGE_PATH_NOT_EXPORTED?

ERR_PACKAGE_PATH_NOT_EXPORTED is a Node.js runtime error thrown when your code attempts to import or require() a file path inside an npm package that the package intentionally does not expose. Node.js enforces the "exports" map in package.json strictly: any subpath not listed there is treated as private and inaccessible — even if the file physically exists on disk.

This is a deliberate encapsulation mechanism. Package authors use it to define a stable public API and prevent consumers from depending on internal implementation paths. When a package adds or updates its "exports" field, previously reachable deep imports suddenly fail with this error.

Example: package that triggers the error

// node_modules/some-package/package.json
{
  "name": "some-package",
  "exports": {
    ".": "./dist/index.js"
  }
}

// your code – this BREAKS
import { helper } from 'some-package/lib/utils';
// → Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/utils' is not defined by "exports"

// your code – this WORKS
import { helper } from 'some-package';
// → resolves to ./dist/index.js ✓

Common Causes Table

How to Fix ERR_PACKAGE_PATH_NOT_EXPORTED

Fix 1 – Use only the package's public API (most common fix)

Read the error message to get the package name and subpath. Then check the package's README, changelog, or the exports field in node_modules/<package>/package.json for the correct replacement.

// uuid – the most frequent real-world case
// Before (broken since uuid v8)
import uuidv4 from 'uuid/v4';

// After (ESM)
import { v4 as uuidv4 } from 'uuid';

// After (CommonJS)
const { v4: uuidv4 } = require('uuid');

// Generic deep import → root import
// Before (broken)
import { helper } from 'some-package/lib/utils';

// After (correct – use the documented export)
import { helper } from 'some-package';
// or the documented named subpath:
import { helper } from 'some-package/utils';

Fix 2 – Add the missing export (if you own the package)

Open your package's package.json and add the subpath to the "exports" field. Use wildcard patterns to expose whole directories.

// package.json – add any subpath you need to make importable
{
  "name": "my-package",
  "exports": {
    ".": "./dist/index.js",
    "./utils": "./dist/utils.js",
    "./models/*": "./dist/models/*.js",
    "./package.json": "./package.json"
  }
}

Fix 3 – Backwards-compatible exports (for package authors)

When you add an exports field for the first time, all existing deep imports instantly break for consumers unless you explicitly list them. Use this pattern to make the addition non-breaking:

{
  "main": "./lib/index.js",
  "exports": {
    ".": "./lib/index.js",
    "./lib": "./lib/index.js",
    "./lib/index": "./lib/index.js",
    "./lib/index.js": "./lib/index.js",
    "./package.json": "./package.json",
    "./lib/*": "./lib/*.js",
    "./lib/*.js": "./lib/*.js"
  }
}

Fix 4 – Pin to an older version

If the package added the exports map in a recent release and broke your import, pin to the last version that did not have it while you migrate:

npm install some-package@2.3.0

Check the package's GitHub releases or CHANGELOG.md to identify which version introduced the exports field.

Fix 5 – Clean reinstall (fix stale node_modules)

A corrupted or mixed-version node_modules tree can expose an older package.json that has a different exports map. A clean reinstall resolves this:

# macOS / Linux
rm -rf node_modules
rm -f package-lock.json
npm cache clean --force
npm install

# Windows (Command Prompt)
rd /s /q node_modules
del package-lock.json
npm cache clean --force
npm install

Fix 6 – Patch with patch-package

If you cannot change your import path and cannot upgrade, use patch-package to add the missing export to the dependency's package.json without changing your import path:

# 1. Manually edit node_modules/some-package/package.json to add the missing subpath
# 2. Create the patch file
npx patch-package some-package

# 3. Apply patches automatically after every npm install (add to package.json)
# "scripts": { "postinstall": "patch-package" }

Fix 7 – Alias via bundler (webpack / Vite / esbuild)

Map the private path to a public equivalent inside your bundler config instead of importing the private path directly.

// vite.config.ts
import { defineConfig } from 'vite';
export default defineConfig({
  resolve: {
    alias: {
      'some-package/lib/utils': 'some-package/utils'
    }
  }
});

// webpack.config.js
module.exports = {
  resolve: {
    alias: {
      'some-package/lib/utils': require.resolve('some-package/utils')
    }
  }
};

Fix 8 – Fix Jest (v28+ or moduleNameMapper)

Jest versions before 28 do not honour the exports field. Upgrade to Jest 28+ for native support. For per-package workarounds, add a moduleNameMapper:

// jest.config.js
module.exports = {
  moduleNameMapper: {
    // Remap the unexported path to the correct public export
    '^some-package/lib/utils$': '<rootDir>/node_modules/some-package/dist/utils.js'
  }
};

# Run Jest with experimental VM modules for ESM packages
node --experimental-vm-modules node_modules/.bin/jest

Conditional Exports – Mismatch Scenario

Modern packages use conditional exports to serve different files for ESM and CJS consumers. If your environment doesn't match any condition and no "default" is defined, Node.js throws ERR_PACKAGE_PATH_NOT_EXPORTED:

// Misconfigured – missing "default" causes error if environment doesn't match
{
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js"
      // no "default" → ERR_PACKAGE_PATH_NOT_EXPORTED in unexpected runtimes
    }
  }
}

// Correct – always include "default" as the last condition
{
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js",
      "default": "./dist/index.js"
    }
  }
}

Intentionally Private Paths (null exports)

The exports field supports null values to explicitly block access to certain subpaths. This is an intentional design choice — the package author is signaling that those paths are private implementation details:

{
  "exports": {
    "./features/*.js": "./src/features/*.js",
    "./features/private-internal/*": null   // explicitly blocked
  }
}

// This throws ERR_PACKAGE_PATH_NOT_EXPORTED — blocked by null
import m from 'es-module-package/features/private-internal/m.js';

If a package intentionally blocks a path with null, you cannot work around it without patching the package. You must use the public API.

TypeScript and moduleResolution

TypeScript's legacy "moduleResolution": "node" does not understand the exports field. TypeScript may compile successfully while the emitted JavaScript fails at runtime with ERR_PACKAGE_PATH_NOT_EXPORTED. Update tsconfig.json to use a modern resolution mode:

// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "bundler",   // best for Vite, esbuild, webpack
    // or:
    "moduleResolution": "node16",    // for native Node.js ESM with package.json type:module
    // or:
    "moduleResolution": "nodenext"   // strict Node.js ESM resolution
  }
}

Affected Node.js Versions

Debugging Checklist

1. Read the error message — it tells you the exact package name and subpath that is missing.
2. Open node_modules/<package>/package.json and inspect the exports field to see what paths are actually available.
3. Check the package's GitHub releases or CHANGELOG.md for migration notes — the new import path is usually documented there.
4. Search the package's issue tracker for ERR_PACKAGE_PATH_NOT_EXPORTED — you are almost certainly not alone.
5. Run node --version to confirm you are on a version that enforces exports (12.17+).
6. Run npm list <package-name> to check if multiple conflicting versions of the package are installed.
7. If the error appeared after npm install with no code changes, do a clean reinstall — a stale lockfile can install mixed versions.
8. If you are in a TypeScript project, verify your "moduleResolution" setting in tsconfig.json is "node16", "nodenext", or "bundler".

Real-World Package Examples

Frequently Asked Questions

{
  "exports": {
    ".": "./dist/index.js",
    "./utils": "./dist/utils.js",
    "./models/*": "./dist/models/*.js",
    "./package.json": "./package.json"
  }
}

Related Errors

• Error: Cannot find module (MODULE_NOT_FOUND) — the file doesn't exist at all (vs. existing but not exported)
• ERR_REQUIRE_ESM — trying to require() a pure ES module; often appears together with ERR_PACKAGE_PATH_NOT_EXPORTED when migrating packages
• SyntaxError: Cannot use import statement in a module — ESM/CJS interop errors that appear in the same module system migration context
• ERR_PACKAGE_IMPORT_NOT_DEFINED — the "imports" map (self-referencing) equivalent of this error; occurs with #internal-style package imports