Node.js / Node.js

Node.js ERR_MODULE_NOT_FOUND

Fix Node.js ERR_MODULE_NOT_FOUND errors in ES module projects.

General troubleshooting guidance Last updated May 10, 2026 0 sources Needs local verification

Category: Node.js
Error signature: Error [ERR_MODULE_NOT_FOUND]
Quick fix: Check the exact import specifier, include required file extensions for relative ESM imports, and reinstall dependencies.
Updated: May 10, 2026
Verification status: General troubleshooting guidance
Evidence: 0 public source URLs

Before you change production

This page does not expose source URLs in the page body. Treat it as general troubleshooting guidance and verify against official documentation before changing systems.

Reproduce the smallest failing action and save non-secret logs before changing configuration.
Check versions for Node.js, related SDKs, package managers, CI runners, and hosting providers.
Change one setting or dependency at a time, then rerun the same failing command or request.
Avoid destructive commands, credential rotation, billing changes, or security relaxations without a rollback plan.

What this error means

Error [ERR_MODULE_NOT_FOUND] means npm or Node.js cannot resolve the project files, package metadata, dependency graph, or module path required by the command. Check the project root, lockfile, and Node version first.

Why this happens

Node projects depend on a consistent relationship between package.json, lockfiles, installed modules, and runtime version.

For Node.js ERR_MODULE_NOT_FOUND, local success can be misleading if node_modules is stale or the lockfile was not regenerated.

Common causes

Relative import is missing a file extension
Package is not installed
Path points to a CommonJS-only entry incorrectly
Case-sensitive filesystem reveals a path mismatch

Quick fixes

Run the command from the folder containing package.json.
Check the exact import specifier, include required file extensions for relative ESM imports, and reinstall dependencies.
Check node --version and npm --version.
Use npm ci for a clean lockfile-based install when a lockfile exists.

Copy-paste commands

Check runtime versions

node --version
npm --version

Install dependencies

npm install

Clean CI-style install

npm ci

Clear npm cache

npm cache clean --force

Reset local install state

rm -rf node_modules package-lock.json
npm install

Platform-specific fixes

CI/CD

Prefer npm ci in CI so the build fails when package.json and package-lock.json drift apart.

Real-world fixes

If the error names a peer dependency, update the plugin and framework versions together.
If the error names a missing file, check filename casing; CI often runs on a case-sensitive filesystem.
Check the exact import specifier, include required file extensions for relative ESM imports, and reinstall dependencies.

Step-by-step troubleshooting

Find the first Error [ERR_MODULE_NOT_FOUND] occurrence in the npm output; later stack lines are often symptoms.
Confirm the command is running in the intended package directory.
Compare package.json and package-lock.json after dependency changes.
Remove stale node_modules only after checking whether the lockfile is committed.
Rerun the failing command with the same Node version used in CI or production.

How to prevent it

Commit lockfile changes with dependency changes.
Pin the project Node version in .nvmrc, .node-version, or CI configuration.
Use CI to catch dependency drift before deploy.

Diagnostic flow for this page

Match Error [ERR_MODULE_NOT_FOUND] exactly before applying the quick fix.
Compare the failing environment with Node.js versions, account scope, provider settings, and deployment context.
Check the listed common causes in order, starting with the cause that best matches your logs.
Use the evidence status below to decide whether to confirm against public sources or official documentation.
Apply one reversible change, rerun the smallest failing action, and keep rollback notes.

FAQ

What does Error [ERR_MODULE_NOT_FOUND] mean in Node.js?

Error [ERR_MODULE_NOT_FOUND] indicates the workflow described by "Node.js ERR_MODULE_NOT_FOUND" failed in a Node.js context. Start by confirming the exact signature and the component that emitted it.

What should I check first for Error [ERR_MODULE_NOT_FOUND]?

Check whether this cause matches your environment: Relative import is missing a file extension

Is the Error [ERR_MODULE_NOT_FOUND] guidance source-backed?

The "Node.js ERR_MODULE_NOT_FOUND" page is labeled general troubleshooting guidance. It has no public source URLs in the current Markdown record, so use that evidence status when deciding how much additional verification you need.

When should I avoid the quick fix for Error [ERR_MODULE_NOT_FOUND]?

For "Node.js ERR_MODULE_NOT_FOUND", avoid applying "Check the exact import specifier, include required file extensions for relative ESM imports, and reinstall dependencies." when the error text differs, the affected version or provider is different, or the change would touch credentials, billing, DNS, production deploy settings, or irreversible data.

What should I collect before debugging Error [ERR_MODULE_NOT_FOUND]?

For "Node.js ERR_MODULE_NOT_FOUND", collect the failing Node.js command or request, non-secret configuration, versions, timestamps, request IDs when available, and the smallest reproduction that still triggers the signature.