Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

ERR_MODULE_NOT_FOUND: Cannot find module imported from an ESM file

ESM resolves specifiers literally: extensions are required, directories do not resolve to index files, and exports maps block deep imports.

~5 min readNode.js
#Node.js#ESM#Modules#Migration
An ESM import arrow missing its file extension plate, amber unresolved module slot, cyan exports gate

Introduction & Quick Summary

text
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/app/lib/config' imported from /app/src/server.js

Node's ESM loader does not guess. It takes the specifier literally, resolves it with the ESM algorithm, and fails when the resulting path does not exist. The four reasons this happens after a migration or an upgrade:

  • The extension is missing. ESM requires ./config.js, not ./config, even for .ts files that are compiled before running.
  • A directory is imported. import "./lib" never resolves to lib/index.js; only the directory's package.json exports or an explicit file does.
  • exports in the dependency's package.json hides the path. A deep import that worked under CommonJS fails because the package does not list that subpath.
  • Case or symlinks. Linux resolves ./Config.js and ./config.js differently, and a symlinked workspace path resolves to its real path unless --preserve-symlinks is set.
Error textMeaningFirst fix
Cannot find module '/app/lib/config' imported from ...Relative specifier without extensionAdd .js to the specifier
Cannot find package 'yaml' imported from ...Bare specifier not installed for that packageInstall it in the right workspace
Package subpath './dist/x.js' is not defined by "exports"exports map blocks the deep pathImport the public entry
Directory import ... is not supportedImported a folderPoint at the file
Cannot find module only on Linux CICase mismatch or symlinkMatch case, check workspace links

Core Mechanics, Signatures & Reproducible Setup

ESM resolution has three phases: relative and absolute specifiers resolve as URLs against the importing module, bare specifiers resolve through node_modules with the exports map, and the result must exist as a file. There is no extension probing, no index.js fallback, and no NODE_PATH.

A reproducible failure is one file and one import:

{ "name": "app", "type": "module", "scripts": { "start": "node src/server.js" } }
js
// src/server.js import { loadConfig } from "./lib/config"; // ERR_MODULE_NOT_FOUND console.log(loadConfig());
bash
node src/server.js # Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/app/src/lib/config' imported from /app/src/server.js

Both repairs are one character and one path:

js
import { loadConfig } from "./lib/config.js";
js
// src/lib/config.js export function loadConfig() { return { port: Number(process.env.PORT ?? 3000) }; }

The specifier is now a real file. Adding "type": "module" is what made the old CommonJS-style resolution illegal in the first place; a .cjs file or "type": "commonjs" keeps require semantics and the old probing.

Key Comparison Table

The resolver in use decides which specifiers are legal, so the first question is not "where is the file" but "which resolver is running".

LoaderExtension requiredDirectory indexBare subpath blocked by exportsExtension probing
require (CJS)NoYesNo.js, .json, .node
import (ESM)YesNoYesNone
tsx / ts-node/esmNo, resolves TSNoYes.ts, .tsx
Bundler (moduleResolution: "bundler")NoYesYesYes, at build time
Jest with ts-jest (CJS)NoYesNo.ts, .js

The exports field changes what a dependency exposes. A package that ships exports is a closed surface, which is a common source of "Cannot find module" after a minor upgrade.

exports valueimport "pkg"import "pkg/sub"import "pkg/dist/sub.js"
Not presentmainAny fileAny file
"./sub": "./sub.js"mainsub.jsBlocked
"./*": "./*"mainAny fileAny file
Only "." definedmainBlockedBlocked

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

Add extensions everywhere, or use a bundler

Once "type": "module" is set, every relative import in every file needs the extension. Adding it to the file that failed only moves the error to the next import.

bash
# list relative imports without an extension grep -rnE "from \"\.{1,2}/[^\"]+\"" src | grep -vE "\.(js|mjs|json|css)\""
js
// before import { db } from "./db"; import { routes } from "./routes/index"; // after import { db } from "./db.js"; import { routes } from "./routes/index.js";

If the codebase is TypeScript and the build outputs ESM, write .js in the source even though the file is .ts. TypeScript keeps the specifier as written under module: "NodeNext", so .js points at the compiled output and the type checker still finds db.ts.

{ "compilerOptions": { "module": "NodeNext", "moduleResolution": "NodeNext", "target": "ES2022" } }

Directory imports and package.json tricks

A directory import fails in ESM, and the replacement is either an explicit file or an exports entry in the directory's own package.json.

js
import { routes } from "./routes"; // Directory import is not supported
js
import { routes } from "./routes/index.js";
{ "name": "@app/routes", "type": "module", "exports": { ".": "./index.js" } }

The package.json form only works when the directory is a package, that is, when it has its own manifest and is resolved as a bare specifier or via a workspace link.

exports maps and deep imports

A dependency upgrade that adds exports closes every path it does not list. The error names the package and the blocked subpath, and no amount of reinstalling helps.

{ "name": "yaml", "exports": { ".": { "import": "./dist/index.js", "require": "./dist/index.cjs" } } }
js
import { parse } from "yaml/dist/index.js"; // subpath is not defined by "exports" import { parse } from "yaml"; // public entry

When the deep path is genuinely needed, the fix is in the dependency (add a subpath) or in the choice of dependency, not in the app's import. Patching node_modules disappears on the next install.

Symlinked workspaces resolve to real paths

A workspace link is a symlink, and ESM resolves the real path of the importing file by default. A package that lives outside the checked-out tree then cannot see its sibling node_modules.

bash
ls -l node_modules/@app/shared # symlink to ../../packages/shared node --preserve-symlinks --preserve-symlinks-main dist/server.js
{ "scripts": { "start": "node --preserve-symlinks --preserve-symlinks-main dist/server.js" } }

The flag solves the symptom for local development. The durable fix is a workspace-aware install (npm workspaces, pnpm, or Yarn nodeLinker: node-modules) so every package resolves against the hoisted tree.

TypeScript, tsc output and .js specifiers

Compiling to ESM with module: "ESNext" and moduleResolution: "bundler" lets the source omit extensions, but node dist/index.js still fails because the emitted JavaScript keeps the specifiers exactly as written.

ts
// source: passes the type checker under "bundler" import { loadConfig } from "./lib/config";
ts
// source: correct for Node ESM output import { loadConfig } from "./lib/config.js";

The alternative is a loader that resolves extensions at runtime, such as tsx in development and a bundler for production, plus an explicit decision that the output is not run by plain node.

Case sensitivity and one-off CI failures

macOS and Windows resolve ./Config.js to config.js; Linux does not. A test suite that passes on a laptop and fails in CI is usually this.

bash
# find import specifiers whose case does not match the file on disk git ls-files | sed 's/.*\///' | sort | uniq -c | sort -rn | head
bash
# reproduce the Linux view without a container node --experimental-loader ./case-check.mjs dist/server.js

The fix is always to make the specifier match the file name exactly, including extensions and the directory's own case.

Common Compilation/Runtime Mistakes & Version Gotchas

Adding "type": "module" to fix an unrelated warning. It converts every .js file in the package to ESM, so every require and every extensionless import breaks at once. Add it deliberately, or rename files to .mjs/.cjs.

Reaching for --experimental-specifier-resolution=node. The flag was removed in Node 20 after being deprecated in 18; passing it on a current runtime is ignored or an error, and extensionless imports still fail.

Assuming the package is installed because it is in package.json. A workspace dependency hoisted to the wrong place, or an optional dependency skipped by --omit=optional, produces Cannot find package at runtime with a clean install.

Ignoring the imported from path. The error names both sides. When the importing path is a dist/ file, the specifier came from a compiler or bundler; when it is node_modules/.pnpm/..., a transitive dependency is importing a path its own manifest does not expose.

Version notes. Node 12 through 18 accept --experimental-specifier-resolution=node; 20 and later removed it. Node 22 adds require(esm) for synchronous graphs, which changes some CJS-to-ESM failures but not the extension rule for import. TypeScript 5.x keeps specifiers under NodeNext; bundler resolution changes only type checking, never runtime.

Triage order: read the imported from path, add the extension, then check the dependency's exports. When the offending specifier is generated, search the build output rather than the source, and use the JSON formatter to read a dependency's package.json exports map directly, or the regex tester to list every relative import in the tree before a migration.

Official references: Node.js errors, ERR_MODULE_NOT_FOUND and ECMAScript modules.

Official references

primary documentation

The Node.js documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Node.js guides

More in Node.js

All Node.js guides

The guides filed next to this one in Node.js, in library order.