Fix “Error: Cannot find module” in Node.js (MODULE_NOT_FOUND)
On this page
- How Node.js looks for a module
- Case 1: A package is missing
- Monorepos and separate client and server folders
- Case 2: One of your own files can’t be found
- The letter-case trap
- Moved or renamed files
- Case 3: ES modules need the file extension
- Case 4: node_modules is broken
- Case 5: It only fails in production or Docker
- Quick diagnosis
- End long relative paths with import aliases
- Prevent it from reaching production
- Frequently asked questions about “Cannot find module”
- Oh hi there 👋It’s nice to meet you.
- 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:
- Built-in modules such as
node:fsandnode:pathload immediately. - Names starting with
./,../or/are file paths, resolved from the file that contains the import. - Anything else is a package name. Node looks in
node_modulesin 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 installornpm ci;node_modulesis normally not uploaded. - Dev dependencies skipped: production installs omit
devDependencies. Anything the running app imports belongs independencies. - Letter case: the trap described above.
- Docker: copying your local
node_modulesinto the image, or mounting a volume over it, hides the modules installed during the build. Addnode_modulesto.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.jsbefore 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
- Read the name in the error. No dot at the start: it is a package. Starts with
./: it is your file. - Package: run
npm ls <name>in the folder with the code. Not listed? Install it there. - File: open the importing file and follow the path by hand, folder by folder, checking spelling and case.
- ES modules: add the file extension.
- Still failing: delete
node_modulesand 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.jsonand install withnpm ci, so every machine gets the same dependency tree. - Add a lint rule such as
import/no-unresolvedfromeslint-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.




