Why npm install fails — 4 causes and how to fix each

npm install, you wait, and instead of green — a wall of red npm ERR!. Familiar and infuriating. But the good news: almost every npm install failure is one of four causes, and they're fixed with a couple of commands, not a reinstall of everything under the sun. Let's go through them in order — most common to rarest — so you know what to press.

First, read the error — half the answer is there

Before you Google, read the first red lines. npm almost always says what's wrong: ERESOLVE, EACCES, ENOTFOUND, “Unsupported engine.” These codes point straight at a cause below. Copying the whole error and feeding it to an AI is also a working move; how to do that well is in the guide on how to debug with AI.

Now the causes.

Cause 1. The wrong Node version (most common)

A project often needs a specific Node version — the library was built for it. You have a different one → the build fails, sometimes with a murky error about engine or an unclear module.

How to check: node -v shows your version. Look in the project's package.json: if there's an "engines": { "node": ">=20" } block and you have 18 — there's your cause. The project README often names the required version too.

How to fix: install the needed Node version. Easiest via a version manager (nvm): nvm install 20 && nvm use 20. It keeps several versions side by side and switches per project — a must-have once you have more than one project.

Cause 2. A broken cache or node_modules

Sometimes an install died halfway (the network blinked, you hit Ctrl+C), and the node_modules folder is left half-built. After that any install trips over its own junk.

How to check: the error looks chaotic — one module, then another, changing on retry. A sure sign of a “dirty” state.

How to fix — three commands, wipe and rebuild clean:

1. rm -rf node_modules — delete the half-built folder (on Windows — rmdir /s /q node_modules).
2. npm cache clean --force — clear the npm cache.
3. npm install — install from scratch.

This fixes a surprising number of cases. When in doubt after “magical” errors — start here.

Cause 3. A dependency conflict (ERESOLVE)

The error ERESOLVE unable to resolve dependency tree. In plain terms: two libraries want different, incompatible versions of a third, and npm doesn't know whom to obey.

How to check: npm spells out in the error who clashed with whom — “package A wants B version 2, but package C wants version 3.”

How to fix:

• First, update the conflicting packages to fresh versions (npm install package@latest) — often the conflict is already gone in newer ones.
• If it's urgent and you need it now — npm install --legacy-peer-deps. This tells npm “don't be so strict about peer dependencies.” A working crutch, but a crutch: it silences the warning rather than resolving the incompatibility, so come back and sort it out later.
• Don't grab --force blindly — it installs known-incompatible things and can build something broken.

Cause 4. Network, proxy, permissions

Rarer, but it happens. ENOTFOUND or a timeout — npm couldn't reach the registry (no network, a VPN/proxy, a mirror is down). EACCES — not enough write permissions.

How to check and fix:

• ENOTFOUND/timeout: check the internet, turn off VPN/proxy, retry. On a corporate network you may need your own registry.
• EACCES: do not solve it with sudo npm install — that's a common bad tip that mangles permissions worse. Better — fix the owner of the npm folder or use nvm, which installs everything in your home folder without admin rights.

If you want to understand what npm even does and where all these packages come from — that's the job of a package manager, and the big picture is there.

What's package-lock.json and should I touch it?

package-lock.json pins the exact versions of everything installed, so it builds the same for you and for someone else. Don't hand-edit it. But if dependencies are truly tangled, it helps to delete node_modules and package-lock.json, then npm install — npm rebuilds the lock from scratch. Just don't delete package.json — that one you must not touch, it's the list of your dependencies.

Should I switch to pnpm?

If npm keeps hurting — yes, worth a try. pnpm installs the same packages but faster and lighter on disk, and it handles conflicts more strictly and clearly. The commands are nearly the same (pnpm install). Many projects sit on pnpm precisely because of less dependency pain.