Fix: npm ERR! ERESOLVE unable to resolve dependency tree

The Error

When running npm install, you get something like this:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-library@2.3.1
npm ERR! node_modules/some-library
npm ERR!   some-library@"^2.3.1" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

The key lines are the Found: and Could not resolve dependency: blocks. They tell you exactly which packages are in conflict and what versions each side expects.

Why This Happens

Peer dependencies are a way for a package to say “I don’t bundle this dependency myself — I expect the project that installs me to provide it.” A common example: a React component library declares react as a peer dependency because it expects your project to already have React installed.

The conflict occurs when two or more packages disagree on which version of a shared peer dependency should be installed.

Why npm 7+ Is Stricter

This is the core of the issue. Before npm 7, peer dependency conflicts were treated as warnings. npm would print a message and move on. Starting with npm 7 (and continuing in npm 8, 9, and 10), peer dependency conflicts are treated as errors that block installation entirely.

The npm team made this change because silently installing incompatible peer dependencies caused hard-to-debug runtime errors. The stricter behavior forces you to address the conflict upfront rather than discovering it later when your app crashes.

If your project worked fine before upgrading npm (or before upgrading Node.js, which bundles a newer npm), this is almost certainly why.

Fix

Solution 1: Use --legacy-peer-deps

This tells npm to use the old npm 6 behavior and ignore peer dependency conflicts:

npm install --legacy-peer-deps

To make this the default for your project, create or edit an .npmrc file in your project root:

legacy-peer-deps=true

This is the quickest fix and is safe in most cases. The peer dependency mismatch often doesn’t cause actual runtime issues — many libraries work fine across a wider range of versions than their peer dependency declarations suggest.

When to avoid this: If the conflicting packages truly are incompatible at runtime (e.g., a library uses an API that was removed in the version you have installed), this will just defer the problem.

Solution 2: Use --force

npm install --force

This is more aggressive than --legacy-peer-deps. It forces npm to fetch packages even if they would cause conflicts, and it will also overwrite packages that were previously installed with a different version. It still installs the conflicting dependencies but bypasses the resolution checks.

Use --legacy-peer-deps first. Only reach for --force if that doesn’t work.

Solution 3: Resolve the Conflict in package.json

This is the correct long-term fix. Read the error output carefully — it tells you exactly which versions conflict.

For example, if the error says:

• Found: react@18.2.0
• Peer dependency requires: react@"^17.0.0"

You have two options:

A. Upgrade the library that has the outdated peer dependency:

npm install some-library@latest

Check the library’s changelog or npm page to see if a newer version supports your current dependency.

B. Downgrade the dependency to match what the library expects:

npm install react@17 react-dom@17

Only do this if you’re not relying on features from the newer version.

Solution 4: Use npm overrides

If you know the library works fine with your version despite the declared peer dependency, you can override the resolution. In your package.json, add:

{
  "overrides": {
    "some-library": {
      "react": "$react"
    }
  }
}

The $react syntax tells npm to use whatever version of react is defined in your top-level dependencies. This forces some-library to accept your project’s version of React.

For more targeted overrides:

{
  "overrides": {
    "react": "18.2.0"
  }
}

This sets a global override for react across all nested dependencies.

Note: overrides was introduced in npm 8.3. If you’re on an older version, upgrade npm first: npm install -g npm@latest.

Solution 5: Delete node_modules and package-lock.json

Sometimes the lockfile itself contains stale resolution data that causes the conflict. Start fresh:

rm -rf node_modules package-lock.json
npm install

On Windows (Command Prompt):

rmdir /s /q node_modules
del package-lock.json
npm install

This forces npm to resolve the entire dependency tree from scratch. If the conflict was caused by a stale lockfile rather than an actual version mismatch, this alone can fix it. If you get a Cannot find module error after reinstalling, see Fix: Error Cannot find module.

Edge Cases

React 18 with Libraries Expecting React 17

This is by far the most common instance of this error. Many popular libraries (older versions of Material UI, React Router v5, some testing libraries) declared "react": "^17.0.0" as a peer dependency before React 18 was released.

Best approach: Check if there’s an updated version of the library that supports React 18. Most actively maintained libraries have released updates. If not, --legacy-peer-deps is safe here — React 18 is backward-compatible with React 17 APIs in nearly all cases.

Conflicting TypeScript Versions

Some packages pin specific TypeScript version ranges as peer dependencies. If you see conflicts involving typescript, check which versions each package requires. Related TypeScript issues like missing module type declarations can also surface after resolving version conflicts.

npm ls typescript

Often you can resolve this by pinning a TypeScript version that satisfies all parties. For example, if one package wants typescript@^4.7.0 and another wants typescript@^4.9.0, installing typescript@4.9 satisfies both.

Monorepos

In monorepo setups (using npm workspaces, Nx, or Turborepo), peer dependency conflicts are more likely because multiple packages may declare different versions of the same dependency.

For npm workspaces, set overrides at the root package.json level. Overrides defined in workspace packages are ignored — only the root-level overrides take effect.

{
  "workspaces": ["packages/*"],
  "overrides": {
    "typescript": "5.3.3"
  }
}

If you’re using Yarn instead of npm, the equivalent feature is resolutions:

{
  "resolutions": {
    "typescript": "5.3.3"
  }
}

Still Not Working?

1. Read the full error output. The npm ERR! lines contain the exact package names and version ranges in conflict. The fix depends on which packages are involved.

2. Check the npm-debug.log file (path is printed at the bottom of the error). It contains the full dependency resolution tree and can reveal transitive (nested) conflicts that aren’t obvious from the summary.

3. Inspect your dependency tree:

   npm ls --all

   This shows every installed package and its dependencies. Look for version mismatches and duplicates.

4. Try a different package manager. If you’re stuck, pnpm and Yarn handle peer dependencies differently and may resolve the conflict automatically. You can try without committing to a switch:

   npx pnpm install

5. Open an issue upstream. If a library’s peer dependency range is too narrow and the library actually works with newer versions, file an issue or PR asking the maintainer to widen the range. This helps everyone.

Related: If you’re getting permission errors when installing npm packages globally, see Fix: EACCES permission denied when installing npm packages globally.