How to Fix npm install Errors: The 3 Codes That Matter

Your npm install just failed, and the terminal is showing you a wall of red. Before you copy the error into a search box, do one thing: scroll up to the line that starts with npm error code. That code is the diagnosis, and it already tells you which of three problems you have. This is how to fix npm install error the fast way — read the code, run the one fix that matches it.

I reproduced all three of the common codes this morning on a real project (Node v24.22.1, npm 10.9.4), and every error and fix below is the actual output. Most guides list ten generic fixes and tell you to try them until something works — including the one npm itself warns you about.

How to fix npm install error: read the code first

npm prints the code right at the top of the error block:

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree

Three codes cover the large majority of failures: ERESOLVE (a version conflict), EACCES (a permission problem), and ENOENT (a file npm can't find). Each one has exactly one correct fix and several wrong ones. Find your code below and skip the rest.

One warning first: the most-copied advice for npm failures is to delete node_modules and package-lock.json and reinstall. It sometimes works, because it throws away the state that was broken. But it also throws away the known-good resolution your lockfile recorded. It's a last resort, not a first step.

ERESOLVE: two packages want different versions of the same thing

This is the most common npm failure today. Here's the real thing, reproduced this morning:

$ npm install [email protected] [email protected]

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error While resolving: [email protected]
npm error Found: [email protected]
npm error Could not resolve dependency:
npm error peer react@"^18.3.1" from [email protected]

Read it literally. You asked for React 19, and react-dom 18.3.1 declares a peer dependency on React ^18.3.1 — that caret means "18.x only, not 19." Since npm 7, peer dependency conflicts fail the install instead of being silently ignored, which is why this error barely existed before 2021 and is everywhere now.

There are two fixes, and they are not equal. The real fix is to align the versions — install the pair that actually agrees with each other:

npm install [email protected] [email protected]

That installed cleanly — "added 3 packages in 2s" — and a version check confirmed react 19.0.0 and react-dom 19.0.0 side by side. When the conflict is between two packages you chose directly, aligning them is almost always possible, and it's the only fix that leaves your dependency tree honest.

The workaround is --legacy-peer-deps. It also works — "added 5 packages in 3s" — by telling npm to resolve peer dependencies the way npm 6 did, ignoring the conflict:

npm install [email protected] [email protected] --legacy-peer-deps

But read what npm itself says: the flag accepts "an incorrect (and potentially broken) dependency resolution." The npm docs are blunter — --legacy-peer-deps is not recommended, because it stops enforcing the peer dependency contract other packages rely on. React 18-era code running against React 19 can fail at runtime in ways that look nothing like an install error.

So: align versions when you can, which is most of the time. Reach for --legacy-peer-deps only when a dependency you don't control pins an old peer range — and leave a comment explaining why, because the next person to run npm install will otherwise "fix" it by removing the flag.

EACCES: npm can't write where it's trying to install

This one shows up on global installs. Reproduced as an unprivileged user this morning:

$ npm install -g is-odd --prefix=/usr/local

npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

The error is honest: npm tried to create a directory inside /usr/local, and your user doesn't own that directory. The tempting fix is sudo npm install -g. Don't. It works once, and then every file it creates belongs to root — so the next install without sudo fails, and soon your whole toolchain needs root to work around a problem you created.

The npm docs give two real fixes. The recommended one is to install Node through a version manager like nvm, which puts Node and npm inside your home directory, where you already have write permission — no sudo, no permission errors, ever. The quicker fix, if you already have a working Node install, is to move npm's global directory into your home folder:

npm config set prefix ~/.local

Then add ~/.local/bin to your PATH (in ~/.profile, or ~/.zprofile for zsh), reload the shell, and test with a global install — no sudo. The same cause shows up on servers, where the deploy user doesn't own the install directory; I wrote about deploying a Next.js app on a VPS the production way, and the rule is the same — the deploy user owns the directories it writes to, or the deploy isn't finished.

ENOENT: npm can't find the file it's looking for

The third code is the most embarrassing, which is why nobody writes about it. Reproduced by running npm install in an empty directory:

npm error path /tmp/npm-repro/enoent/package.json
npm error errno -2
npm error enoent Could not read package.json: Error: ENOENT:
  no such file or directory, open '/tmp/npm-repro/enoent/package.json'

ENOENT means "no such file or directory," and here the missing file is package.json itself. npm installs the dependencies listed in package.json in the current directory; run it from anywhere else and there's nothing to install. The fix is to cd into the project root first and run it again. A quick ls before you install saves more debugging time than any flag. The same code also appears when a script references a file that doesn't exist — a renamed folder, a deleted config. The error names the path. Believe it.

The order that actually works

Put it together and the whole procedure fits on an index card:

1. Read the code. Scroll to npm error code XXXX. That's your diagnosis.
2. Check you're in the right directory. pwd and ls package.json take two seconds and catch every ENOENT.
3. Check your versions. node -v and npm -v — if a package needs Node 20 and you're on 16, no flag will save you.
4. Run the fix for your code. ERESOLVE: align the versions, --legacy-peer-deps only as a documented last resort. EACCES: move the global prefix or switch to a version manager, never sudo. ENOENT: fix the path.
5. Only then, the nuclear option. If the code doesn't match any of the three — or the error survives the matching fix — delete node_modules, clear the cache with npm cache clean --force, and reinstall. If it works after that, check the lockfile diff before you commit it.

And if the install succeeds but the app is still slow, the problem was never the install — it's what the app does at runtime. Finding a memory leak in Node.js starts from the same place this post does: stop guessing, measure the thing that's actually broken.

The pattern behind all three codes is the same: npm already knows what went wrong. It prints the code, names the file or the package, and in the ERESOLVE case even tells you which two versions disagree. Read the code, run the matching fix, and you're back to writing code in minutes.

References

• Resolving EACCES permissions errors when installing packages globally — npm Docs
• npm config: legacy-peer-deps — npm Docs
• Why npm install Is Not Working and How to Fix It — C# Corner
• How to fix npm install command not working — Sebhastian
• Troubleshooting npm install Errors — readmedium