npm ERESOLVE "Unable to Resolve Dependency Tree": What It Means and How to Fix It

You run npm install and get a wall of red text:

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: my-app@0.1.0
npm error Found: react@19.1.0
npm error Could not resolve dependency:
npm error peer react@"^17.0.0 || ^18.0.0" from some-date-picker@4.2.0

It looks scary, but it's telling you one specific thing, and there's a sensible order of fixes.

What it means

Some packages declare peer dependencies: "I work with React, but I don't bring my own copy — I expect your project to have one, in this version range."

The error above says:

• Your project has React 19.1.0.
• some-date-picker@4.2.0 says it needs React 17 or 18 (^17.0.0 || ^18.0.0).
• npm can't satisfy both, so it refuses to guess.

That refusal is npm protecting you. Installing anyway might work, or might break in subtle ways at runtime. (The ^ and || are version ranges — see semantic versioning explained.)

How to read it

Find three things in the error:

1. "Found:" — the version you have (react@19.1.0).
2. "peer ... from ..." — which package is complaining and what it wants (some-date-picker@4.2.0 wants React 17 or 18).
3. "While resolving:" — usually your own project.

Now you know the conflict: the date picker doesn't officially support my React version.

The fixes, in order of preference

1. Upgrade the complaining package

The package may have released a version that supports your React. Check:

npm view some-date-picker peerDependencies
npm view some-date-picker versions

or look at its changelog. If a newer version supports React 19:

npm install some-date-picker@latest

This is the best fix — everyone's requirements are genuinely met.

2. Replace the package

If the package is abandoned (no release in years, open issues about your framework version), switch to a maintained alternative. Ask your AI tool to suggest one — and check it exists and is popular before installing (AI hallucinated a package).

3. Match versions deliberately

Sometimes the problem is that your version is the odd one out — for example an AI tool installed a pre-release or mismatched versions of related packages (react and react-dom must match). Align them.

4. Override, knowingly

If you've checked that the package actually works with your version (many do, they just haven't updated their declared range), tell npm explicitly with overrides in package.json:

"overrides": {
  "some-date-picker": {
    "react": "$react"
  }
}

This says "for that package, use whatever React my project uses". It's recorded in your project, so everyone gets the same behaviour.

5. --legacy-peer-deps (last resort)

npm install --legacy-peer-deps

This tells npm to ignore peer dependency conflicts entirely — the behaviour of npm 6 and earlier. It "fixes" the install by not checking. Acceptable as a temporary measure if you've confirmed things work, but:

• it applies to all peer conflicts, hiding future ones;
• teammates and your deploy server must use the same flag, or their installs fail. If you rely on it, put legacy-peer-deps=true in an .npmrc file in the project so it's consistent.

Avoid --force

npm install --force pushes through conflicts and can install a broken tree. Avoid it unless you know exactly why you need it.

Don't delete the lockfile as a reflex

A common AI-suggested "fix" is deleting package-lock.json and node_modules and reinstalling. That can resolve stale states, but it also upgrades many unrelated packages at once, which can introduce new bugs. Do it deliberately, commit first, and test afterwards. (How to update dependencies safely.)

The summary

• ERESOLVE means a package's peer dependency range doesn't include the version your project has.
• Read "Found" and "peer ... from ..." to identify the conflict.
• Best fixes: upgrade the package, replace it, or align versions.
• Use overrides when you've verified compatibility; --legacy-peer-deps only as a last resort; avoid --force.

---

EasySpawn keeps your dependencies installed on persistent storage and gives Claude Code a real environment to run npm install, build and test — so dependency problems get fixed and verified in one place. See how it works or join the waitlist.

Related: What Are npm and package.json? · npm vs pnpm vs Yarn vs Bun · How to Read an Error Message · npm audit Explained