Node.js throws a ModuleNotFoundError when it cannot locate a required module in the node_modules directory or module resolution paths. This typically happens when a package is not installed or the import path is incorrect.
The "Cannot find module" error occurs when Node.js's module resolution system fails to locate a package you're trying to import or require. Node.js searches for modules in several locations: the local node_modules folder, parent directories up the file tree, and global installation paths. When the specified module isn't found in any of these locations, Node.js throws a ModuleNotFoundError. This error is one of the most common issues developers encounter when working with Node.js applications, especially when setting up new projects, cloning repositories, or managing dependencies. The module system expects packages to be properly installed and available in the node_modules directory before they can be imported. Understanding Node.js module resolution is key to fixing this error. Node.js follows a specific algorithm: it starts looking for the module in the current directory's node_modules, then checks parent directories recursively until it reaches the root. For npm packages, the module must be listed in package.json dependencies and physically present in node_modules after running npm install.
Run npm install with the package name to add it to your project:
npm install lodashFor packages only needed in development (like testing frameworks), use:
npm install --save-dev lodashThis adds the package to node_modules and updates package.json automatically.
If you've just cloned a repository or package.json exists but node_modules is missing, install all dependencies:
npm installThis reads package.json and installs all listed dependencies. For projects using Yarn or pnpm:
# Yarn
yarn install
# pnpm
pnpm installCheck your import or require statement for typos:
// Incorrect
const _ = require('lodash'); // but you typed 'lodas'
// Correct
const _ = require('lodash');Module names are case-sensitive. Verify the exact name by checking npmjs.com or the package documentation.
Open package.json and verify the module is listed:
{
"dependencies": {
"lodash": "^4.17.21"
}
}If it's missing, either add it manually and run npm install, or use npm install lodash to add it automatically. Ensure production dependencies aren't listed under devDependencies.
If installation seems successful but the error persists, clear the npm cache:
# Clear npm cache
npm cache clean --force
# Delete node_modules and lockfile
rm -rf node_modules package-lock.json
# Reinstall everything
npm installOn Windows, use:
# Delete folders
Remove-Item -Recurse -Force node_modules, package-lock.json
# Reinstall
npm installFor custom local modules, use relative paths with ./ or ../:
// Incorrect - Node looks in node_modules
const utils = require('utils');
// Correct - Explicitly references local file
const utils = require('./utils');
const config = require('../config');Local modules without ./ or ../ are treated as npm packages.
Check that your Node.js and npm versions meet the project requirements:
node --version
npm --versionSome packages require specific Node.js versions. Check package.json for an engines field:
{
"engines": {
"node": ">=18.0.0"
}
}Use nvm (Node Version Manager) to switch versions if needed:
nvm install 18
nvm use 18TypeScript Projects: If using TypeScript, you may also need to install type definitions for packages that don't include them:
npm install --save-dev @types/lodashType definition packages follow the @types/ namespace convention. Not all packages require thisโmany modern packages include TypeScript definitions automatically.
Module Resolution Debugging: Use Node.js's --trace-warnings flag to see detailed module resolution attempts:
node --trace-warnings index.jsYou can also check which version of a package is installed using:
npm list lodashMonorepo Considerations: In monorepo setups using workspaces (npm workspaces, Yarn workspaces, or pnpm workspaces), modules are hoisted to the root node_modules. Ensure you're running install commands from the correct directory and that workspace dependencies are properly linked.
ESM vs CommonJS: ES modules use import syntax while CommonJS uses require(). If you see "Cannot use import outside a module", add "type": "module" to package.json or use .mjs file extensions. Mixing module systems can cause resolution issues.
Production Environment Issues: If the error only occurs in production, verify that:
- package.json includes all dependencies (not just devDependencies)
- CI/CD pipeline runs npm ci (which installs from package-lock.json) instead of npm install
- NODE_ENV is set correctly and doesn't skip dependency installation
- Docker containers include the COPY package*.json and RUN npm ci steps
Debugging with npm ls: Check the entire dependency tree for missing or conflicting packages:
# List all dependencies
npm ls
# Check specific package
npm ls lodash
# Show only problems
npm ls --depth=0Error: EMFILE: too many open files, watch
EMFILE: fs.watch() limit exceeded
Error: Middleware next() called multiple times (next() invoked twice)
Express middleware next() called multiple times
Error: Worker failed to initialize (worker startup error)
Worker failed to initialize in Node.js
Error: EMFILE: too many open files, open 'file.txt'
EMFILE: too many open files
Error: cluster.fork() failed (cannot create child process)
cluster.fork() failed - Cannot create child process