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.

Introduction & Quick Summary
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/app/lib/config' imported from /app/src/server.jsNode'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.tsfiles that are compiled before running. - A directory is imported.
import "./lib"never resolves tolib/index.js; only the directory'spackage.jsonexportsor an explicit file does. exportsin the dependency'spackage.jsonhides the path. A deep import that worked under CommonJS fails because the package does not list that subpath.- Case or symlinks. Linux resolves
./Config.jsand./config.jsdifferently, and a symlinked workspace path resolves to its real path unless--preserve-symlinksis set.
| Error text | Meaning | First fix |
|---|---|---|
Cannot find module '/app/lib/config' imported from ... | Relative specifier without extension | Add .js to the specifier |
Cannot find package 'yaml' imported from ... | Bare specifier not installed for that package | Install it in the right workspace |
Package subpath './dist/x.js' is not defined by "exports" | exports map blocks the deep path | Import the public entry |
Directory import ... is not supported | Imported a folder | Point at the file |
Cannot find module only on Linux CI | Case mismatch or symlink | Match 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" }
}// src/server.js
import { loadConfig } from "./lib/config"; // ERR_MODULE_NOT_FOUND
console.log(loadConfig());node src/server.js
# Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/app/src/lib/config' imported from /app/src/server.jsBoth repairs are one character and one path:
import { loadConfig } from "./lib/config.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".
| Loader | Extension required | Directory index | Bare subpath blocked by exports | Extension probing |
|---|---|---|---|---|
require (CJS) | No | Yes | No | .js, .json, .node |
import (ESM) | Yes | No | Yes | None |
tsx / ts-node/esm | No, resolves TS | No | Yes | .ts, .tsx |
Bundler (moduleResolution: "bundler") | No | Yes | Yes | Yes, at build time |
Jest with ts-jest (CJS) | No | Yes | No | .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 value | import "pkg" | import "pkg/sub" | import "pkg/dist/sub.js" |
|---|---|---|---|
| Not present | main | Any file | Any file |
"./sub": "./sub.js" | main | sub.js | Blocked |
"./*": "./*" | main | Any file | Any file |
Only "." defined | main | Blocked | Blocked |
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.
# list relative imports without an extension
grep -rnE "from \"\.{1,2}/[^\"]+\"" src | grep -vE "\.(js|mjs|json|css)\"" // 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.
import { routes } from "./routes"; // Directory import is not supportedimport { 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" }
}
}import { parse } from "yaml/dist/index.js"; // subpath is not defined by "exports"
import { parse } from "yaml"; // public entryWhen 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.
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.
// source: passes the type checker under "bundler"
import { loadConfig } from "./lib/config";// 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.
# find import specifiers whose case does not match the file on disk
git ls-files | sed 's/.*\///' | sort | uniq -c | sort -rn | head# reproduce the Linux view without a container
node --experimental-loader ./case-check.mjs dist/server.jsThe 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 documentationThe Node.js documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Node.js guides
All Node.js guidesStripe webhooks: no signatures found matching the expected signature
Verification needs the exact bytes Stripe sent and the endpoint's own secret. Fix parser order, proxy re-encoding and edge runtime crypto.
npm ci: the lock file is out of sync and how to fix it correctly
The lock and the manifest disagree, and CI stops before installing. Regenerate on the same npm major and keep platform entries.
pnpm: Ignored build scripts and how to approve them
A skipped postinstall leaves native modules empty. Approve the packages once in committed config, then verify the build instead of allowing everything.
Node.js 26 upgrade: rmdir, native addons and removed flags
Three breaks stop a deploy: rmdir with recursive throws, the transform-types flag is gone, and the module ABI moved to 147.
More in Node.js
All Node.js guidesThe guides filed next to this one in Node.js, in library order.