Node.js MODULE_NOT_FOUND on a Package Subpath - Fix Deep Import

A subpath import fails with MODULE_NOT_FOUND when the path you reached for does not exist in what the registry published - a missing build artifact, a renamed file, or a path the package never shipped.

What this error means

Requiring or importing a deep path like pkg/dist/foo.js throws Cannot find module with MODULE_NOT_FOUND, while importing the package root works. It often appears only in CI, where a clean install reveals the published file layout your local node_modules masked.

Node output

Error: Cannot find module 'some-pkg/dist/helpers'
Require stack:
- /app/src/index.js
    at Function._resolveFilename (node:internal/modules/cjs/loader)
    code: 'MODULE_NOT_FOUND'

Common causes

The subpath is not in the published tarball

A package’s files/build only ships certain paths. A deep import to a file that exists in the repo but not in the published package fails on a clean install.

The internal layout changed across versions

An upgrade renamed or relocated dist/ files. The old subpath you hard-coded no longer resolves to anything.

A stale local node_modules hid the problem

Your machine had an older copy with the file; CI installs the current version cleanly and the missing subpath surfaces.

How to fix it

Inspect what the package actually ships

List the installed package contents and import a path that exists (ideally the public entry).

Terminal

ls node_modules/some-pkg/dist
# then import a real path, or the root:
node -e "console.log(require.resolve('some-pkg'))"

Use the public API, not internal paths

Prefer the documented root import over reaching into dist/.
If a subpath moved, update to the new published path.
Bust a stale node_modules cache so CI and local agree on the layout.

How to prevent it

Import documented entry points rather than build internals.
Re-verify deep imports after dependency upgrades.
Run a clean npm ci so the real published layout is tested.