The "Cannot find module" issue in Node.js happens when the runtime is unable to detect a necessary dependency. Incorrect routes, missing installs, or configuration problems are usually the cause of this. Root causes, solutions, and best practices for fixing the mistake are explained in this tutorial.

Conceptual Background
Node.js loads modules using the require or import syntax. The runtime searches in the following order:

• Core modules (e.g., fs, path)
• node_modules folder in the current directory
• Parent directories up to the system root

When the requested module cannot be located in this resolution path, Node.js throws:

Error: Cannot find module 'MODULE_NAME'

Step-by-Step Walkthrough
1. Check the Module Name

• Ensure the module name is spelled correctly.
• Common mistakes: case sensitivity (express vs Express) or typos.

// Wrong (typo)
const exress = require('exress');

// Correct
const express = require('express');

2. Install Missing Dependencies
npm install MODULE_NAME

or with yarn
yarn add MODULE_NAME

Example
npm install express

3. Verify Local vs Global Installations
Some modules are installed globally, but Node.js expects them locally.

Check if installed
npm list MODULE_NAME

If missing locally
npm install MODULE_NAME

4. Fix File Path Requires
When requiring local files, always use relative or absolute paths.
// Wrong (missing ./)
const config = require('config');

// Correct (relative path)
const config = require('./config');

5. Clear Node.js Cache
Sometimes cached modules cause issues. Clear cache:
npm cache clean --force

Then reinstall
rm -rf node_modules package-lock.json
npm install

6. Check NODE_PATH Environment Variable
If you rely on custom paths, ensure NODE_PATH is set correctly.

On macOS/Linux
export NODE_PATH=./src

On Windows (PowerShell)
$env:NODE_PATH = ".\src"

7. Use Absolute Paths with path.resolve
For complex directory structures, avoid relative path confusion:
const path = require('path');
const config = require(path.resolve(__dirname, 'config.js'));

Code Snippet Example

// index.js
const express = require('express');
const path = require('path');
const config = require(path.resolve(__dirname, 'config.js'));

const app = express();
app.get('/', (req, res) => {
res.send('Hello, World!');
});
app.listen(3000, () => console.log('Server running on port 3000'));

Workflow JSON Example
{
  "name": "fix-node-module-error",
  "steps": [
    { "check": "Verify spelling of module name" },
    { "command": "npm install MODULE_NAME" },
    { "check": "Ensure local installation in node_modules" },
    { "fix": "Add ./ for relative file imports" },
    { "command": "npm cache clean --force" },
    { "command": "rm -rf node_modules package-lock.json && npm install" }
  ]
}

Use Cases / Scenarios

• Web applications using Express.js where express is missing.
• CLI tools failing due to global vs local installs.
• Microservices with deep folder structures requiring absolute paths.

Limitations / Considerations

• Clearing the cache removes all installed packages; it may require reinstallation.
• Global modules are not accessible in local projects by default.
• Path resolution may vary across operating systems.

Fixes for Common Pitfalls

• Typos → Double-check module names.
• Wrong relative path → Always use ./ for local files.
• Corrupted node_modules → Delete and reinstall.
• Environment misconfiguration → Ensure correct NODE_PATH.