Why does npm ci fail when npm install works?

npm ci strictly follows the committed lockfile. If package.json and package-lock.json disagree, regenerate and commit the lockfile.

Home JavaScriptPackages and imports

npmIntermediateMedium severity

npm ERR! ERESOLVE unable to resolve dependency tree

npm found incompatible peer dependency requirements while building the install plan.

10-20 min Popularity 95/100 Verified 2026-07-21

Debug with AI

What does this error mean?

Two or more packages require incompatible versions of the same dependency, and npm cannot choose a version that satisfies every declared peer range.

Why does this happen?

A framework was upgraded without upgrading its plugins.
A package declares an outdated peer dependency range.
The lockfile contains a stale resolution.
A prerelease package is mixed with stable dependencies.

AI explanation

Plain-English analysis

Peer dependencies are compatibility claims between packages. npm found claims that cannot all be true at the same time, so it stopped rather than installing a combination that may break at runtime.

Quick fix

Terminal

npm explain <package>
npm outdated
npm install <compatible-version>

Expected output: npm completes the install without an ERESOLVE report.

Step-by-step fix

1Align the conflicting package versionsRead the ERESOLVE report from the first conflict and install versions with overlapping peer ranges.80%

2Regenerate the lockfileUse this after package.json has been corrected but the lockfile still preserves an obsolete resolution.47%

Command

rm -rf node_modules package-lock.json
npm install

3Use legacy peer dependency behavior temporarilyThis bypasses peer resolution and should be a temporary compatibility measure.22%

Command

npm install --legacy-peer-deps

Alternative solutions

Windows PowerShell

Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

Only regenerate after checking the declared dependency versions.

CI

npm ci

Commit a valid lockfile and keep CI installs deterministic.

Real example

Broken

json

"react": "19.2.4",
"legacy-plugin": "1.0.0" // peer requires React 17

Corrected