npm error ERESOLVE — unable to resolve dependency tree
Filed under Deployment failures
Two packages in your project demand incompatible versions of the same dependency, and modern npm refuses to guess which one should win.
Fastest route
Give your AI this prompt
Copy it, replace the bracketed part with your error, and send it.
Preview the prompt
npm install is failing with "ERESOLVE unable to resolve dependency tree". Here is the full error output: [paste the whole error, especially the "While resolving", "Found", and "Could not resolve dependency" lines]. I was trying to [install package X / just run npm install] when it happened. My package.json dependencies are: [paste the dependencies section]. Please: 1) name the two packages in conflict and the version ranges that collide, in plain English, 2) try the clean fix first — tell me which package to update (or which compatible release of the new package to use) so the ranges align, 3) only if alignment is not possible, set up the legacy-peer-deps route properly, including an .npmrc file so deployments install the same way. Constraints: do not delete package-lock.json as a first move, do not use --force as the permanent solution, and tell me which fix you applied and why.
Fix it yourself
Follow the repair
- Read the report — npm names the exact conflict. The wall of text has a readable core. Look for the lines like:
Translated: your project has React 19; the library you are adding declares it supports React 18 only. Those two names and numbers are the whole diagnosis — everything else in the output is echo.While resolving: [email protected] Found: [email protected] Could not resolve dependency: peer react@"^18" from [email protected] - Try updating the package that is behind. If an existing package is the one demanding the old version, update it:
npm install that-package@latest. Current releases widen their peer ranges as the ecosystem moves, so one update dissolves most conflicts properly — no flags, no compromises, a tree npm is fully happy with. This is always the first move. - Check the new package against your framework version. When the newcomer is the problem, look at its releases: is there a newer version that declares support for your React or Next.js version? Install that one. If the library simply has not caught up yet, your real choices are a different library that has, waiting, or the pragmatic install in step 4 — but knowing which situation you are in comes first.
- Install with --legacy-peer-deps to confirm the app works. Run
npm install --legacy-peer-deps. This tells npm to use its older, relaxed behaviour — install what was asked, warn instead of refusing. Then do the important part: actually run the app and use the feature that needed the package. Peer ranges are partly caution; many "conflicting" combinations work perfectly. If the feature works, this is a legitimate resolution. If it breaks at runtime, the conflict was real, and you need aligned versions or a different package. - Make the setting stick for deploys with .npmrc. Fixing your machine is not enough: Vercel and every other host run a fresh
npm installand will hit the identical wall, turning your local fix into a failed deployment. Create a file named.npmrcin the project root containing one line:
Commit it with the project. Now every install — yours, your builder's, your host's — plays by the same rules.legacy-peer-deps=true - Avoid --force as the standing answer. You will see
npm install --forcerecommended in forums. It bulldozes the check entirely rather than restoring the older compatibility behaviour, applies only to that single run, and leaves the next install — including your deployment — to fail again. Fine as a five-minute experiment; as the permanent arrangement, legacy-peer-deps or aligned versions are the durable answers.
Why this happensOptional explanation
Your project does not give every package its own private set of tools. Dependencies form one shared tree: if three packages all use the same charting library underneath, ideally they share one agreed version of it. Packages declare what they can live with in their peer dependency ranges — "I work with React 18 or 19," say — and modern npm (version 7 and later) checks that every declaration in the tree can be satisfied simultaneously. When two ranges do not overlap, there is no legal tree, and npm stops the install with ERESOLVE rather than silently installing a combination one package swears will break it.
This is why the error so often appears the moment an AI builder adds something. The builder asks for a new package; the new package's peer range was written against last year's framework; your project has already moved on. Nothing is corrupt — the arithmetic just does not close. Older npm versions guessed and warned; current ones refuse, which is safer and much louder about it.
- One package is behind: an older library clings to an old version of a shared dependency everything else has left behind.
- The new package has not caught up: its peer range predates your version of React or Next.js.
- A major version just landed: you upgraded the framework; half the ecosystem still declares the previous one.
- npm got stricter: projects that installed fine years ago can fail today on the same versions, purely because the checking changed.
Quick answers
Is --legacy-peer-deps dangerous to use?
It restores the older, more relaxed npm behaviour: install what was asked for and warn about peer conflicts instead of refusing. It is widely used and usually fine. The honest caveat: if the two versions genuinely cannot work together, the bug moves to runtime instead of install time — so install this way, then actually test the feature that uses the package.
Why did adding one package break the whole install?
Because dependencies are a single shared tree, not private copies per package. Your new package declared which versions of a shared library it can live with, and that range collided with the version another package already requires. One package, one collision, one refusal — npm is being cautious on your behalf, loudly.
Should I delete package-lock.json and node_modules?
Only after the versions are decided. Regenerating the lock file with aligned versions gives you a clean, reproducible tree. Deleting it while the conflict is still real just makes npm re-derive the same contradiction, possibly with newer versions than you tested.