Your AI coding agent ran npm install and got ERESOLVE unable to resolve dependency tree

npm install fails with ERESOLVE after an AI agent adds a package that does not support your React version. Here is what peer dependencies mean, why pnpm hides it, and the fixes from safest to riskiest.

מעבר לתיקון
בעמוד הזה

Your AI coding agent adds a UI library or a plugin, runs npm install, and the terminal fills with npm error code ERESOLVE and ERESOLVE unable to resolve dependency tree. Nothing in your own code changed. The agent usually reacts by retrying with a flag it picked at random, and the install “works” while quietly leaving you with a tree npm said was wrong.

This is a version conflict between your project and the package’s declared peer dependencies, and there are three ways out with very different costs.

Why this happens

A package can declare peerDependencies: the host library it expects you to already have, at a compatible version. The npm docs note that as of npm v7, peer dependencies are installed by default. So when you run npm install some-package, npm checks that your react version satisfies what that package asked for. If it does not, the install fails with ERESOLVE instead of guessing.

The common trigger is a new major version of a core library. The shadcn/ui docs describe it for React 19: when a package does not list React 19 as a peer dependency, npm stops with the ERESOLVE error naming the conflicting react version. The same page says this is npm only: “PNPM and Bun will only show a silent warning.” That is why an agent that built the project with pnpm may never have seen the error, and your npm install is the first place it appears.

How to tell if this is your problem

  1. Read the error, not just the headline. The lines under ERESOLVE name the package that wants a version, the version you have, and the range it asked for. For example, a package asking for react@"^18" while your project has React 19.
  2. Check which package manager the project uses. A pnpm-lock.yaml or bun.lock next to package.json means the project was not built with npm.
  3. Check your version. npm ls react shows what your tree resolves to.

The fix, cheapest-to-riskiest

1. Use the package manager the project already uses

If the lockfile belongs to pnpm, Bun or yarn, install with that tool. The shadcn docs say pnpm, Bun and yarn need no flags for this case.

2. Check for a newer release of the package

The conflict usually means the package has not widened its peer range yet. Look at its latest version or its issue tracker before forcing anything.

3. Tell npm to proceed, knowing what you are skipping

The shadcn docs offer two flags for npm, and both install the package while ignoring the peer dependency warnings:

npm i <package> --legacy-peer-deps

The npm docs describe --legacy-peer-deps as making npm “completely ignore peerDependencies when building a package tree, as in npm versions 3 through 6”, and say its use “is not recommended, as it will not enforce the peerDependencies contract that meta-dependencies may rely on.” The --force flag is broader: the same docs list it as removing “various protections” and say that if you do not have a clear idea of what you want, you should not use it. Prefer --legacy-peer-deps over --force for this error, and run the app afterwards, because the package may genuinely not work with your React version.

To make it stick for teammates and CI, put legacy-peer-deps=true in a .npmrc file in the project root, so that a plain npm install behaves the same everywhere.

4. Downgrade the core library

The shadcn docs also list installing React 18 instead (npm i react@18 react-dom@18) as an option when a package is not ready for 19. Only do this if nothing else in the project needs 19.

5. Pin the one conflicting package with overrides

The npm docs describe overrides as a way to replace a package in your dependency tree with another version. It is only read from the root package.json, and you cannot override a package you depend on directly unless the spec matches or you use the $ reference syntax. It is the narrowest tool: it fixes one package instead of switching peer checks off for the whole project.

How to avoid this next time

Tell the agent up front: “This project uses npm. When an install fails with ERESOLVE, show me the conflicting package and version range before using —force or —legacy-peer-deps, and never add a flag without saying why.” After any forced install, run the app and your build once before committing the lockfile.

Comments