Node

Fix “Error: Cannot find module” in Node.js (MODULE_NOT_FOUND)

Fix “Error: Cannot find module” in Node.js (MODULE_NOT_FOUND)
On this page
  1. How Node.js looks for a module
  2. Case 1: A package is missing
  3. Monorepos and separate client and server folders
  4. Case 2: One of your own files can’t be found
  5. The letter-case trap
  6. Moved or renamed files
  7. Case 3: ES modules need the file extension
  8. Case 4: node_modules is broken
  9. Case 5: It only fails in production or Docker
  10. Quick diagnosis
  11. End long relative paths with import aliases
  12. Prevent it from reaching production
  13. Frequently asked questions about “Cannot find module”
  14. Oh hi there 👋It’s nice to meet you.
  15. Sign up to receive awesome content in your inbox.

You start your app and Node.js stops with Error: Cannot find module ‘express’, or a path such as './utils/math'. The error code is MODULE_NOT_FOUND, and it means exactly that: Node looked where the rules say to look and found nothing. The fix depends on whether the missing thing is a package or one of your own files. This guide covers both, with every error message below reproduced on Node.js 22.

How Node.js looks for a module

Knowing the lookup order tells you where to fix the problem:

How Node.js looks for a moduleNode checks built-in modules, then relative paths that start with ./ or ../, then node_modules folders from the current folder upward; if nothing matches, it reports Cannot find module.Built-in?'node:fs'loads at onceStarts with ./ ?a file pathexact path and casenode_modulesthis folder, then upnpm installNot foundMODULE_NOT_FOUNDthe error
Node checks built-in modules, then file paths, then node_modules folders, before reporting the error.
  1. Built-in modules such as node:fs and node:path load immediately.
  2. Names starting with ./, ../ or / are file paths, resolved from the file that contains the import.
  3. Anything else is a package name. Node looks in node_modules in the current folder, then in each parent folder up to the root.

The first thing to read in the error is therefore the name in quotes: does it start with a dot, or not?

Case 1: A package is missing

Error: Cannot find module 'express'

The name has no ./, so Node searched node_modules and didn’t find it. Work through these:

Cause Fix
The package was never installed npm install express
You cloned a project and didn’t install its dependencies npm install in the folder containing package.json
You ran the command in the wrong folder cd into the project, then run it again
It is installed globally, not in the project Install it locally: npm install <name>
It is in devDependencies but production installs skip those Move it to dependencies: npm install <name> --save-prod
A typo in the name Check the spelling against the package’s npm page

To see whether Node can find a package, and where, ask it directly. In testing, this printed the exact file Node would load:

node -e "console.log(require.resolve('mongoose'))"
# …/node_modules/mongoose/index.js

If that command fails with the same error, the package isn’t installed where Node is looking. npm ls express shows whether, and at which version, a package is installed in the current project.

Monorepos and separate client and server folders

In a MERN project with client/ and server/ folders, each has its own package.json and node_modules. Installing express in the project root or in client/ doesn’t make it available to server/. Run npm install inside the folder whose code needs the package.

Case 2: One of your own files can’t be found

Error: Cannot find module './utils/math'

The name starts with ./, so it is a path relative to the file doing the import, not to the folder you ran node from. With math.js inside src/utils/, these were the results from a file in the project root:

Code Result
require('./utils/math') Cannot find module: the path skips the src folder
require('src/utils/math') Cannot find module: without ./, Node treats it as a package name
require('./src/utils/Math') Cannot find module: wrong letter case
require('./src/utils/math') Works ✅

The letter-case trap

The third row deserves attention. Windows and macOS file systems usually ignore letter case, so ./Math finds math.js on your laptop. Linux, which runs almost every server and container, is case-sensitive, and the same code fails there. This is the classic cause of “works on my machine, crashes after deployment”. Match the exact case of every file and folder name, and keep a consistent naming style so mistakes stand out.

Moved or renamed files

After moving a file, every import that points to it, and every relative import inside it, needs updating. Your editor can do this automatically if you rename files through it rather than in the file manager.

Case 3: ES modules need the file extension

In projects using import, with "type": "module" in package.json, the error has a different code and a helpful hint:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/app/src/utils/math' imported from /app/index.mjs
Did you mean to import "./src/utils/math.js"?

CommonJS adds .js for you and can load a folder’s index.js. ES modules do neither: you must write the full file name.

import { add } from './src/utils/math';      // ❌ ERR_MODULE_NOT_FOUND
import { add } from './src/utils/math.js';   // ✅
import routes from './routes/index.js';      // ✅ not just './routes'

A missing package looks slightly different in ES modules, Cannot find package 'lodash', and has the same fix as Case 1. The differences between the two module systems are covered in fixing “Cannot use import statement outside a module” and “require is not defined in ES module scope”.

Case 4: node_modules is broken

If the package is listed in package.json and still isn’t found, the install itself may be incomplete, for example after an interrupted install, switching branches, or changing Node.js versions. Reinstall cleanly:

# macOS and Linux
rm -rf node_modules package-lock.json
npm install

# Windows PowerShell
Remove-Item -Recurse -Force node_modules, package-lock.json
npm install

If your team commits package-lock.json, keep it and delete only node_modules, then run npm ci, which installs exactly the locked versions. More commands are in the npm cheat sheet.

Case 5: It only fails in production or Docker

  • Dependencies not installed on the server: the deploy must run npm install or npm ci; node_modules is normally not uploaded.
  • Dev dependencies skipped: production installs omit devDependencies. Anything the running app imports belongs in dependencies.
  • Letter case: the trap described above.
  • Docker: copying your local node_modules into the image, or mounting a volume over it, hides the modules installed during the build. Add node_modules to .dockerignore.
  • Wrong start file: Cannot find module '/app/server.js' means the file named in your start command doesn’t exist at that path. Check the "start" script and the folder the process runs from.
  • TypeScript: running node dist/index.js before building, or with path aliases that weren’t rewritten, fails this way. Build first, and resolve aliases with your build tool.

A complete deployment setup is in the Node.js production checklist.

Quick diagnosis

  1. Read the name in the error. No dot at the start: it is a package. Starts with ./: it is your file.
  2. Package: run npm ls <name> in the folder with the code. Not listed? Install it there.
  3. File: open the importing file and follow the path by hand, folder by folder, checking spelling and case.
  4. ES modules: add the file extension.
  5. Still failing: delete node_modules and reinstall.

End long relative paths with import aliases

Deep folder structures lead to imports like ../../../utils/sum.js, which break whenever a file moves and are a frequent source of this error. Node.js has a built-in fix: the imports field in package.json, which defines private aliases that start with #:

{
  "type": "module",
  "imports": {
    "#utils/*": "./src/utils/*",
    "#config": "./src/config.js"
  }
}
// src/routes/admin/report.js: no ../../.. needed
import { add } from '#utils/sum.js';
import config from '#config';

In testing, a file three folders deep loaded both modules through the aliases. An alias that isn’t defined fails with a clear, different error, ERR_PACKAGE_IMPORT_NOT_DEFINED, which names the package.json it checked. Because this is part of Node itself, it needs no build tool or extra package, and editors such as VS Code follow the aliases for navigation.

Prevent it from reaching production

  • Run the app in CI on Linux before deploying. A simple start-up check or test run catches missing packages and letter-case mistakes that your own machine hides.
  • Commit package-lock.json and install with npm ci, so every machine gets the same dependency tree.
  • Add a lint rule such as import/no-unresolved from eslint-plugin-import, which flags imports that don’t resolve while you type.
  • Use TypeScript or // @ts-check: unresolved imports become editor errors.

Frequently asked questions about “Cannot find module”

Why does Node say “Cannot find module” for a package I installed?

It was probably installed in a different folder, or globally. Node only looks in node_modules folders from the importing file upward. Run npm install <name> in the project that uses it.

Why does it work on Windows but fail on Linux?

Linux file systems are case-sensitive. An import of ./Math finds math.js on Windows or macOS but not on a Linux server. Match the exact letter case.

What is the difference between MODULE_NOT_FOUND and ERR_MODULE_NOT_FOUND?

The first comes from CommonJS require, the second from ES module import. The causes are the same, but ES modules also require file extensions in relative imports.

Should I install packages globally to fix this?

No. Global packages are for command-line tools. Libraries your code imports should be installed in the project so they are listed in package.json and installed on every machine.

Why does “Cannot find module” mention a file inside node_modules?

A package you installed is missing one of its own dependencies, usually because the install was interrupted. Delete node_modules and run npm install again.

Do I need to restart the server after installing a package?

Yes, if it was already running. Node resolves modules when they are first imported, so a running process doesn’t see packages installed afterwards. Watch tools such as nodemon restart on file changes, but not always on installs, so restart manually.

Why does “Cannot find module” appear only in my tests?

The test runner may resolve paths differently, for example with its own root folder or without your path aliases. Configure the same aliases in the test runner, or use Node’s built-in imports field, which works everywhere.

logo

Oh hi there 👋
It’s nice to meet you.

Sign up to receive awesome content in your inbox.

We don’t spam! Read our privacy policy for more info.

Saurabh

Saurabh Pathak is an AI engineer and MERN stack developer, and the founder of mernstackdev.com. He builds open-source projects such as the Haat gateway and MCP safety tooling, and he writes hands-on tutorials on React, Node.js, MongoDB and AI agents. He cares most about code that works in production.