Maaz Zindani

Loading the index…

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

Node.js cannot load a package folder because its package.json main entry does not resolve

ErrorError: Cannot find module 'some-library'

Short answer

When you require a folder, Node.js reads the main field of its package.json. If main is missing or does not resolve to a file, Node.js tries index.js, index.json and index.node, and reports Cannot find module if those fail too. Make main point to a file that exists after your build.

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

Fix it fast

  1. 1Find out which cause you have

    Read the package's main and exports fields, then check that the file really exists on disk.

    node -p "const p=require('./node_modules/some-library/package.json'); JSON.stringify({main:p.main, exports:p.exports, type:p.type})"
    ls node_modules/some-library
  2. 2Match what you see, then jump to its fix

    1. 1main is something like ./dist/index.js and the dist folder is missingmain points to a file that was never built or was movedFix
    2. 2main looks right, but the import still fails or a subpath is refusedAn exports field takes precedence over mainFix
    3. 3ERR_UNSUPPORTED_DIR_IMPORT or ERR_MODULE_NOT_FOUND from an import statementAn ES module import points at a folder instead of a fileFix

What does the error look like?

  • Error: Cannot find module 'some-library'
  • code: 'MODULE_NOT_FOUND'
  • ERR_MODULE_NOT_FOUND

Cause 1 of 3

main points to a file that was never built or was moved

1Check

Node.js looks up main, then falls back to index.js and index.node in the folder. If the file named by main cannot be resolved, and no index file exists, the whole module is reported missing.

node -p "require('./package.json').main"
ls -l dist

2Fix

Run the build that creates the file before you publish or start the app, or correct the path in main.

npm run build
# package.json
"main": "./dist/index.js"

3Verify

Load the folder the way a consumer does.

node -e "require('.')"

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

An exports field takes precedence over main

1Check

When exports exists, it wins over main for import by package name, and it hides every subpath that it does not list. A request for an unlisted subpath throws ERR_PACKAGE_PATH_NOT_EXPORTED.

node -p "JSON.stringify(require('./package.json').exports, null, 2)"

2Fix

Make exports point to real files, and keep main for older tools. The Node.js docs show both side by side.

{
  "main": "./index.js",
  "exports": "./index.js"
}

3Verify

Import the package by name from another folder.

node -e "require('my-package')"

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

An ES module import points at a folder instead of a file

1Check

The folder lookup through main and index.js only applies to require(). import of a directory fails. Also, a .js file is an ES module only when the nearest package.json has type set to module; .mjs is always ESM and .cjs is always CommonJS.

node -p "require('./package.json').type"

2Fix

Use the file extension or the type field that matches how the file is written, and use a full path with extension in ESM imports.

// ESM import: a directory is not resolved, name the file
import lib from './lib/index.js';

3Verify

Run the entry file.

node ./index.js

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Build before you publish, and check that the file main names exists in the output.
  • Add a smoke test that requires the built package.
  • Keep main and exports pointing to the same built file.

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.