Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js cannot resolve a package: ERR_PACKAGE_PATH_NOT_EXPORTED

ErrorError [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './x' is not defined by "exports"

Short answer

Node.js refuses an import path that the package's exports field does not list. Read the package's package.json exports, then import a listed path, or update or pin the package so versions agree. If you own the package, add the missing subpath or a require or default condition.

  • Applies to Node.js 22, Node.js 24, npm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    The message names the package and the path. Open that package's exports field and compare it with what you or a dependency imports.

    cat node_modules/PACKAGE/package.json
  2. 2Match what you see, then jump to its fix

    1. 1Package subpath './lib/thing.js' is not defined by "exports"You import a file path the package no longer exposesFix
    2. 2The failing path is inside node_modules/ of a build tool, such as a compiler plugin, not in your own codeA dependency of a dependency needs a path that a newer or older copy droppedFix
    3. 3No "exports" main resolved in .../package.jsonNo entry matches how the package is loaded (import or require)Fix
    4. 4Users report the error after you published a release that adds an exports fieldYour own package added exports and broke its usersFix

What does the error look like?

  • Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './x' is not defined by "exports"
  • Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main resolved in /app/node_modules/pkg/package.json

Cause 1 of 4

You import a file path the package no longer exposes

1Check

Once a package defines exports, all subpaths not listed are hidden from importers. require('pkg/subpath.js') then throws this error, even though the file is on disk.

grep -rn "from 'PACKAGE/\|require('PACKAGE/" src/

2Fix

Import only what exports lists.

// before
const x = require('pkg/lib/thing.js');
// after: a path listed in exports
const x = require('pkg/thing');

3Verify

Run the app again; the module loads.

node -e "require('pkg/thing')"

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 4

A dependency of a dependency needs a path that a newer or older copy dropped

1Check

Find which package versions are installed and which package asks for them. Adding exports to an existing package is a breaking change for consumers that use unlisted entry points.

npm ls PACKAGE
npm explain PACKAGE

2Fix

Update the package that makes the import to a release that supports the installed version, or pin the dependency to the version it expects.

npm install PARENT@latest
# or pin the child
npm install PACKAGE@VERSION

3Verify

npm ci removes node_modules and installs exactly what the lock file lists; run the build again after it.

npm ci

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 4

No entry matches how the package is loaded (import or require)

1Check

Conditions in exports are matched in order. The import and require conditions are mutually exclusive, so a main entry that lists neither the one your loader uses nor a default has nothing to resolve. A default condition is the generic fallback and should come last.

cat node_modules/PACKAGE/package.json

2Fix

Load the package the way it supports, for example with import or dynamic import(). If you maintain it, add the missing condition and keep default last.

{
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.cjs",
      "default": "./index.mjs"
    }
  }
}

3Verify

Load it from both styles.

node -e "import('PACKAGE').then(() => console.log('import ok'))"
node -e "require('PACKAGE')"

Confirmed by nodejs.org

Did this fix it?

Cause 4 of 4

Your own package added exports and broke its users

1Check

Adding exports hides every entry point not listed, including package.json itself. The Node.js docs call this likely a breaking change.

git diff PREVIOUS_TAG -- package.json

2Fix

List every entry point that was supported before, and add ./package.json if people read it.

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

3Verify

Require each old path from a test project.

node -e "require('my-package/package.json')"

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Import only documented entry points of a package, not files you found in node_modules.
  • Commit the lock file and install with npm ci, so every machine resolves the same versions.
  • When publishing a package, list every supported entry point before adding exports.
  • Treat adding exports as a breaking change in your release notes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.