Error: Cannot find module 'x'

Node.js · updated 2026-11-02

Thrown at load time by require() (code MODULE_NOT_FOUND) or, for ES modules, as ERR_MODULE_NOT_FOUND. The message names the module and the requireStack shows which file asked for it. When it works locally and fails in production, the difference is almost always what was installed or copied into the production image.

Error: Cannot find module 'dotenv'
Require stack:
- /srv/app/dist/server.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1225:15)
    at Module._load (node:internal/modules/cjs/loader:1051:27)
    at Module.require (node:internal/modules/cjs/loader:1311:19) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/srv/app/dist/server.js' ]
}

Quick fix

If the name is a package, check it is in dependencies (not devDependencies) and that the production install or Docker image contains it. If it is a relative path, check the file exists in the build output with exactly that case: macOS and Windows file systems ignore case, Linux does not, so ./Utils works locally and fails on the server when the file is utils.js.

Read the module name and the first file in requireStack.
Package: confirm it is under dependencies in package.json and present in node_modules on the server or in the image.
Relative path: list the build output directory and compare the file name, including case and extension.
ES modules: relative imports need the file extension (./db.js), and package.json "exports" may not expose the subpath you import.
Rebuild and redeploy from a clean install (npm ci, pnpm install --frozen-lockfile, bun install --frozen-lockfile).

bash

# Is it a runtime dependency?
npm pkg get dependencies.dotenv devDependencies.dotenv

# Is it in the image or on the server?
docker run --rm my-app:latest ls node_modules/dotenv
ls -la dist/lib/   # compare exact file names and case

Why it happens

Listed in devDependencies

Production installs (npm ci --omit=dev, NODE_ENV=production) skip devDependencies, so a package used at runtime but listed there exists locally and is missing in production.

File name case differs

Linux file systems are case-sensitive. An import of ./Config resolves on macOS when the file is config.js, then fails on a Linux server or container.

The build output does not contain the file

A TypeScript or bundler build that skips non-code files, a Dockerfile COPY that misses a folder, or an outDir mismatch leaves the import pointing at nothing.

Missing extension or unexported subpath in ESM

Native ES modules do not add .js for you, and a package with an "exports" map only allows the subpaths it lists, so deep imports that worked in CommonJS fail.

Install never ran or ran for a different platform

A deploy that copies source without node_modules, or a node_modules built on another OS, misses packages or their native binaries.

Other fixes

Run the production build and start it locally from a clean checkout before deploying.
Use a lockfile and a frozen install in CI and in the Dockerfile.
Turn on forceConsistentCasingInFileNames in tsconfig, or an ESLint import rule, to catch case mismatches on macOS.

Same error, other wording

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/srv/app/dist/db' imported from /srv/app/dist/server.js
Error: Cannot find module './Config'
Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/x' is not defined by "exports"

Let your coding agent catch the next one

Runheed records this error in production with the stack trace, the breadcrumbs before it and the agent session that shipped the code, and serves it to Claude Code, Cursor or any MCP client. With it connected, you can ask:

> Find the Cannot find module errors in production, show the module name, the require stack and the release behind the latest one, and work out whether it is a dependency missing from the production install, a case mismatch, or a file missing from the build output.

Plans from $29/mo See what your agent reads See the setupCancel any time from the billing portal