How to Fix npm ERR ERESOLVE Unable to Resolve Dependency Tree

When installing new packages in a JavaScript/TypeScript project, you may encounter a verbose, red terminal crash:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! Found: react@19.0.0
npm ERR! node_modules/react
npm ERR!   react@"^19.0.0" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0" from some-legacy-package@1.2.3

This error halts package installations. It means npm's package solver detected a conflict between the version of a library you already have installed (e.g., React 19) and the version expected by a package you are attempting to install (e.g., React 18).

In this guide, we will analyze why peer dependency checks block builds and walk through four solutions to resolve the conflict.

The Cause: npm 7+ Strict Peer Dependency Installs

A Peer Dependency is a declaration inside a library's package.json stating: "To use me, the host project must already have installed package X at version Y."

The behavior of how package managers handle this has evolved:

• npm v6 and older: If a peer dependency was missing or mismatched, npm logged a yellow warning in the console but proceeded with the installation anyway.
• npm v7 and newer (v7+): npm changed its default behavior to enforce peer dependencies strictly. If there is a version mismatch, npm halts, drops the installation, and throws the ERESOLVE error.

While this protects your build from installing incompatible modules, it often blocks developers from using older libraries that work fine on newer runtime versions.

Solution 1: Use the --legacy-peer-deps Flag (Most Common)

If you know the version mismatch will not break your application (for example, installing a simple React component that works on both React 18 and React 19), you can bypass the check.

Append the --legacy-peer-deps flag to your installation command:

# Tell npm to ignore strict peer dependency rules
npm install some-legacy-package --legacy-peer-deps

This flag instructs npm to fall back to the v6 behavior: it will output warnings about conflicts but force-installs the package.

Solution 2: Force the Installation (--force)

Alternatively, you can use the --force flag:

# Force the installation, overriding existing package locks
npm install some-legacy-package --force

• Difference: While --legacy-peer-deps ignores peer check warning stacks entirely, --force executes a destructive resolution, downloading conflicting versions of dependencies locally to make the tree fit. This can increase your overall node_modules bundle size.

Solution 3: Enforce Specific Versions in package.json (Overrides)

If you are working in a team project where developers run npm install regularly, forcing everyone to type --legacy-peer-deps is prone to error.

You can force npm or pnpm to resolve specific versions of dependencies throughout the entire project tree using the overrides block inside your root package.json:

{
  "name": "my-app",
  "dependencies": {
    "react": "^19.0.0",
    "some-legacy-package": "^1.2.3"
  },
  "overrides": {
    "react": "$react"
  }
}

• "react": "$react": This setting instructs npm that if any sub-dependency requests any version of react, it must override that request and use the root project's declared react version instead.

If you are using Yarn, define this property inside the "resolutions" block instead:

"resolutions": {
  "react": "^19.0.0"
}

Solution 4: Migrate to pnpm

If you are tired of dependency tree blocks and slow resolving times, consider migrating your project to pnpm.

pnpm handles peer dependencies differently. Instead of throwing fatal ERESOLVE errors and stopping your workflow, pnpm resolves conflicts by generating virtual dependency mappings behind the scenes. This allows you to install packages instantly with cleaner tree states.

To migrate, install pnpm globally and run:

# Convert npm configurations to pnpm
pnpm import
pnpm install

Conclusion

The npm ERR! ERESOLVE error is triggered by npm 7+'s strict peer dependency verification system. To resolve these installation blocks, append --legacy-peer-deps to bypass verification checks safely, run --force to overwrite local dependency locks, declare overrides parameters inside package.json to force single library versions across all modules, or migrate your project workspaces to pnpm for flexible package management.