Cannot Find Module in Node? Fix It Fast

You're mid-deploy, the logs look clean, then Node exits with Error: Cannot find module 'express'. Your code hasn't changed. Your tests passed locally. Yet production won't start, and the deploy pipeline is red. This error kills more Node startups than any other, and it almost always traces back to something boring: a package that was never installed, a filename with one wrong letter, or a require path that works on your laptop but not on the server.

The error message actually tells you a lot if you know how to read it. The quoted string is exactly what Node tried to resolve. The stack trace shows which file asked for it. The requireStack field lists the chain of files that led to the failure. Most developers glance at the first line and start reinstalling everything. That's slow and often makes things worse.

This guide walks through Node's resolution algorithm step by step so you can diagnose the failure in under two minutes. You'll learn why extension-less requires break under ESM, why case typos pass on Mac but fail on Linux, and why NODE_PATH should stay your last resort. By the end you'll have a repeatable checklist that turns this panic moment into a five-minute fix.

How Node's Walk-Up Resolution Actually Works

Every bare require like require('express') starts a directory climb. Node takes the importing file's folder, appends node_modules/express, and checks for package.json with a main or exports field. If nothing matches, it moves to the parent folder and repeats, all the way to the root. You can watch this climb yourself: require.resolve.paths('express') prints every directory Node will probe, in order. This design explains why a nested package can shadow a top-level one, and why deleting an inner node_modules suddenly changes which copy loads.

Relative specifiers skip the climb entirely. require('./utils') resolves against the importing file's directory only. Node tries the exact path, then appends .js, .json, and .node. It also handles directory imports by reading package.json main or falling back to index.js. ESM is stricter: import './utils' with no extension is a hard error, and directory imports need an explicit index file. Knowing which branch your specifier takes — climb for bare names, direct lookup for ./ and ../ — tells you exactly where to look when resolution fails.

Package entry points add one more lookup layer you'll use constantly. When Node finds node_modules/express, it reads package.json for the main field (CommonJS) or the exports map (modern packages), falling back to index.js when neither exists. A package missing its entry file throws the same Cannot find module error with the package name quoted, which sends developers reinstalling a package that's installed but broken. Check the entry with node -p "require('express/package.json').main" and confirm the file exists. Scoped packages (@acme/utils) climb identically — the scope is just a folder level. When the climb crosses a monorepo boundary, each workspace's node_modules restarts the search, so verify which workspace's tree the importer actually resolves from.

node -e "console.log(require.resolve.paths('express').join('\n'))"
node -e "console.log(require.resolve('./lib/payments'))"
ls node_modules/express/package.json && node -p "require('express/package.json').version"

Typo'd Package Names: The Fastest Check You'll Ever Run

Misspelled package names are the most common cause and the quickest to rule out. Compare the quoted string in the error against package.json character by character — transposed letters ('experss'), wrong scope ('@acme/util' vs '@acme/utils'), and pluralization slips ('lodash' vs 'lodashes') account for most cases. Scoped packages add a twist: the scope and name must both match, including the slash. Node won't suggest corrections, so eyeballing isn't enough at 2 AM.

Make the check mechanical. Run npm ls <name> to see whether npm recognizes the dependency at all. If it prints empty output, the name in your code doesn't match anything installed. Then run npm view <name> version to confirm the package exists in the registry under that exact spelling. For local files, list the directory and diff the names programmatically instead of trusting your eyes. Two minutes of exact comparison beats twenty minutes of reinstalling the world.

Editor tooling prevents most typos before they reach runtime, so wire it up. VS Code's auto-import completes package names from installed dependencies, and TypeScript's moduleResolution: bundler flags unknown specifiers during type-check instead of at 2 AM in production. When you inherit an unfamiliar codebase, don't trust memory for scoped names — copy specifiers from package.json or let the editor insert them. For published packages, npm search and the registry page confirm exact scope and spelling, including hyphen-vs-underscore traps like node-sass versus node_sass. If a name looks right but still fails, paste it into npm view <exact-string> version: registry confirmation beats another visual scan. You'll catch transposed letters in seconds instead of burning a reinstall cycle that can't fix a spelling error.

npm ls express --depth=0
npm view express version
ls node_modules | grep -i exprs
node -e "try { require.resolve('experss') } catch (e) { console.error(e.code, e.message.split('\n')[0]) }"

Uninstalled Dependencies: When package.json and node_modules Disagree

The second classic is a package that's declared but not installed. It happens after git clone without npm install, when a Dockerfile copies source but skips npm ci, or when someone runs with --omit=dev while the start script needs a devDependency. The error looks identical to a typo, so you must check installation state explicitly. npm ls <name> prints the resolved tree or marks it missing; ls node_modules/<name> verifies the folder physically exists.

The fix depends on the environment. Locally, npm install restores everything from package-lock.json. In CI and Docker, npm ci wipes node_modules and installs exactly what's locked — slower but reproducible. Never hand-edit node_modules or copy folders between machines; that hides version drift the lockfile exists to prevent. If npm ls shows extraneous or invalid, delete node_modules and package-lock drift with a clean npm ci rather than layering installs on top of a broken tree.

Lockfiles are the other half of this story. package-lock.json records the exact tree that worked; npm ci reproduces it byte-for-byte while npm install re-solves ranges and can drift. When a teammate adds a dependency with npm install -S but forgets to commit the lockfile, your fresh clone installs a different tree and the new import fails on your machine only. Make lockfile commits mandatory and review dependency diffs like code. In Docker, order matters for cache and correctness: copy package.json plus the lockfile first, run npm ci, then copy source — so dependency changes bust the cache while source edits reuse it. If an image ships an empty node_modules because install ran in a different stage than runtime, multi-stage COPY --from must carry the built tree forward. You'll never debug phantom-missing packages again once installs are locked, staged, and verified with npm ls in the build log.

npm ls stripe --depth=0
ls node_modules/stripe/package.json
npm ci
node -e "console.log(require.resolve('stripe'))"

Extension-less Requires That Break Under ESM

CommonJS lets you write require('./config') and resolves config.js automatically. ESM does not. The import specifier must include the full filename including extension: import './config.js'. This bites during migrations where files keep their names but switch syntax, and in mixed codebases where .js files use require in one place and import in another. The error code changes too — ERR_MODULE_NOT_FOUND instead of MODULE_NOT_FOUND — which confuses grep-based alert rules.

Decide on one module system per directory and make extensions explicit everywhere. If you must mix, use .mjs for ESM entry points and .cjs for CommonJS helpers so Node never guesses. The exports field in package.json adds another layer: when present, it restricts which subpaths importers can reach, so deep requires like require('pkg/internal') fail even when the file exists. Read the exports map before assuming a path is public.

The exports map deserves a closer look because it fails even experienced developers. When package.json defines exports, Node treats it as an allowlist: only listed subpaths resolve, and everything else throws ERR_MODULE_NOT_FOUND even though the file sits on disk. Library authors add exports maps in minor versions, so a routine bump can block deep imports that worked for years — the fix is importing the documented entry point, not reinstalling. For your own packages, keep exports explicit and test deep paths in CI. Mixed codebases need file-extension discipline: name ESM files .mjs and CommonJS helpers .cjs so the loader never guesses, and set type: module only in packages fully converted to import syntax. A grep for extension-less relative imports in CI (excluding known-safe patterns) turns migration debt into a visible, shrinking list instead of a production surprise.

import db from './db.js';
import { cache } from './cache.js';

export const settings = { db, cache, retries: 3 };

if (process.env.NODE_ENV !== 'test') {
  console.log('config loaded with', Object.keys(settings).length, 'keys');
}

Case Sensitivity: Passes on Mac, Dies on Linux

macOS and Windows default to case-insensitive filesystems: require('./Utils') finds utils.js without complaint. Linux containers are case-sensitive: Utils and utils are different files, and the require throws. Because most developers run Macs while production runs Debian or Alpine, this bug passes every local test and fails every deploy. It's the signature of a Cannot-find-module error that only appears in CI or production.

The durable defense is making your pipeline case-aware. Run CI on ubuntu-latest, add a Linux-based boot test that imports your entry point inside the real container, and enable import/no-unresolved linting. For existing codebases, scan for risky filenames with a case-insensitive duplicate search. Adopt an all-lowercase file naming convention so there's only one way to spell every import. When the error string and the filename differ by case alone, you've found it — fix the import, not the filesystem.

Git adds a nasty twist to case bugs: on case-insensitive systems it may not record a case-only rename at all, leaving the repo and disk disagreeing silently. Force the rename with git mv oldname newname so the change stages explicitly, and verify with git status showing a rename entry rather than silence. Adopt an all-lowercase-with-hyphens convention for every new file — one valid spelling means imports can't diverge. Add a CI check that fails on case-insensitive duplicates (find plus sort -f plus uniq -di takes one line) so violations block the pull request instead of the deploy. When you inherit a codebase with mixed casing, normalize in one codemod commit and update all importers atomically. Don't hand-rename files on the server to match broken imports; that widens the repo-production gap and guarantees the next deploy reintroduces the mismatch.

find src -name '*.js' | sort -f | uniq -di
ls -la src/lib/ | grep -i paym
docker run --rm -v "$PWD:/app" -w /app node:20-alpine node -e "require('/app/server.js'); console.log('boot ok')"

NODE_PATH: The Last Resort That Hides Real Breakage

NODE_PATH adds extra global lookup directories to the resolution climb. In 2012 it papered over immature npm behavior. Today it mostly masks undeclared dependencies: code requires a package that isn't in package.json, works on the one laptop with NODE_PATH set, and fails everywhere else. It also breaks tooling assumptions — bundlers, TypeScript, and editors don't read NODE_PATH consistently, so type-checking and jump-to-definition silently disagree with runtime.

Use NODE_PATH only for diagnosis, never as a fix. If setting it makes the error vanish, you've proven the dependency is undeclared — now declare it with npm install -S and remove the variable. Check shell profiles, Dockerfiles, and CI env blocks for stale NODE_PATH exports when onboarding or debugging a new machine. Clean module boundaries plus explicit relative imports beat global search paths every time.

Finding every NODE_PATH definition is step one of removal. Grep shell profiles (~/.bashrc, ~/.zshrc, ~/.profile), CI env blocks, Dockerfiles (ENV directives persist into every container), and hosting dashboards for the variable — stale exports hide in all of them. Each hit is a machine whose builds can't be trusted until the variable is gone and dependencies declared properly. Replace legitimate uses with modern equivalents: npm workspaces or a monorepo linker for shared local packages, tsconfig paths plus bundler aliases for shortcut imports, and proper -S installs for everything else. After removal, run a clean clone-and-boot on a fresh machine (or container) as the acceptance test — success there proves no hidden path remains. You'll trade one mysterious variable for explicit, reviewable dependency declarations that work identically on every machine your code touches.