Problem: npm install fails with ERESOLVE unable to resolve dependency tree (strict peer deps) —— Trove problem library

What you will run into

An old frontend project (Vue2/webpack 4 era), after switching machines or Node major versions, fails npm install with ERESOLVE unable to resolve dependency tree — no code changed, dependencies just won't install.

The error message actually names both conflicting sides (Found: ... and peer ... from ...) — read the error first, don't rush to delete node_modules.

Why this happens

npm 7+ resolves peerDependencies strictly by default: it auto-installs peer deps and rejects the whole tree if versions don't match. In the npm 6 era, peer mismatches were silently skipped — so the same package.json "works" on old npm. Common triggers:

• Plugin version too old: the plugin's declared peer range doesn't cover the new major of the main dependency (e.g. eslint-plugin-import@2.22.1 peers on eslint ^2~^7.2.0; installing eslint 8 conflicts);
• Two dependencies demand mutually contradictory versions of the same peer, npm can't satisfy both;
• A new machine has newer node/npm, triggering the same resolution-logic difference.

Since npm 7, the resolver treats peerDependencies as hard constraints: it resolves and installs peer deps automatically, and refuses the whole dependency tree when versions do not satisfy (ERESOLVE);

npm 6 and earlier silently skipped (and often did not install) mismatched peers — the same package.json behaves differently across npm versions, which is why "suddenly errors after switching machines/upgrading" happens.

Common ERESOLVE shapes: a plugin's peer range is too old (does not include the newer major of the host), or two dependencies demand mutually contradictory peers (npm cannot satisfy both).

Deterministic takeaway: ERESOLVE means "the resolver says this combination has no solution", not "a package is broken"; fix priority — upgrade the conflicting side (plugin or host to compatible versions) > pin peers explicitly via overrides > --legacy-peer-deps (reverts to npm6 silent behavior;

last resort); after fixing, run npm ls to confirm the tree is consistent; the While resolving chain in the error names both sides — upgrade along it.

Step by step

1. Read the error to locate the conflict (the right fix) — Diagnose

npm view <plugin> peerDependencies

Found: ... and peer ... from ... are the two conflicting sides. Prefer upgrading the plugin to a version supporting the new major, or downgrade the main dependency back into the peer range.

2. Quick bypass — Required

npm install --legacy-peer-deps

Accepts the old npm semantics (--force does the same but cruder). Note this accepts "incorrect and possibly broken" dependency resolution; runtime compat issues may still appear after install — transition only.

3. Full reinstall for old projects — Required

Delete node_modules + package-lock.json and reinstall; or temporarily use npm 6 semantics:

npx -p npm@6 npm install --legacy-peer-deps

No need to uninstall npm 7+; npx pins the version (measured: this machine's npm 9.2.0 vs npx npm@6 = 6.14.18).

4. Team-wide default to skip the check (symptom fix) — Required

Write legacy-peer-deps=true in the project-level .npmrc; long-term, still upgrade dependencies.

How to confirm it works

npm install --legacy-peer-deps && npm ls --depth=0

The tree installing completely means success. Measured: eslint@8.0.0 + eslint-plugin-import@2.22.1 → full ERESOLVE error chain reproduced (exit 1); --legacy-peer-deps → added 232 packages (exit 0); --force → also succeeds.

Other environments

Symptom

Old front-end projects (Vue2/webpack 4 era) fail with:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! While resolving: <your-project>@1.0.0
npm ERR! Found: <installed main dep>@<version>
npm ERR! Could not resolve dependency:
npm ERR! peer <peer-name>@"<peer range>" from <plugin>@<version>

Typical triggers: after switching machines or upgrading the Node major version; the project code is untouched but dependencies won't install. The error names both sides of the conflict (Found: ... / peer ... from ...).

Cause

npm 7+ resolves peerDependencies strictly by default: it auto-installs peer deps and refuses the whole tree when versions don't match. npm 6 silently skipped the peer check, which is why the same package.json "worked" on older npm. Common triggers:

1. Plugin too old: the plugin's peer range excludes the newer main dependency (e.g. eslint-plugin-import@2.22.1 peers eslint ^2~^7.2.0, conflicting with eslint 8);
2. Two dependencies demand incompatible versions of the same peer and npm cannot satisfy both;
3. A fresh machine with a newer node/npm hits the same resolution difference.

Solution

In recommended order:

1. Read the error and fix versions (the right fix): Found: ... and peer ... from ... name the conflicting pair. Upgrade the plugin to one supporting the newer main dep, or downgrade the main dep into the peer range (npm view <pkg> peerDependencies to inspect ranges).
2. Quick bypass (most common): npm install --legacy-peer-deps — skips the strict peer check, restoring old-npm semantics; --force does the same more bluntly. Both accept "incorrect (and potentially broken)" resolutions, so use them as a stopgap.
3. Full reinstall for old projects: delete node_modules + package-lock.json and reinstall; or temporarily use npm 6 semantics: npx -p npm@6 npm install --legacy-peer-deps (no need to uninstall npm 7+, npx picks the version).
4. To make it stick project-wide: .npmrc with legacy-peer-deps=true (stopgap; upgrading deps is still the long-term fix).