Fix "npm install" Peer Dependency Conflicts (ERESOLVE Error)

Introduction

You try to install a simple library like react-datepicker, and your terminal explodes with red text. "ERESOLVE unable to resolve dependency tree."

It lists a confusing tree of packages, version numbers, and "Found: react@19.0.0". This is the dependency hell of modern JavaScript. It happens when two libraries fight over which version of a shared tool (like React) they want to use.

Here is the 30-second fix and the 5-minute proper solution.

The Quick Fix: The Magic Flag

How do I bypass npm peer dependency errors?

To bypass npm peer dependency errors immediately, run your install command with the --legacy-peer-deps flag. This tells npm to ignore the conflict and install the package anyway, assuming the library will likely work with your version.

npm install cool-library --legacy-peer-deps

Note: This is safe 90% of the time, especially when React just released a major version (like v19) and libraries haven't updated their package.json tags yet.

The Proper Fix: Understanding ERESOLVE

When you see this error, npm is protecting you.

Option 1: Force Resolution (overrides)

If you know what you are doing, you can force a version in your package.json.

Add this to your package.json:

"overrides": {
  "react": "$react",
  "react-dom": "$react-dom"
}

This forces all sub-dependencies to use your version of React, effectively silencing the complaints.

Option 2: Downgrade

If the library is critical and breaks with the new version, you might need to downgrade your main dependency.

npm install react@18 react-dom@18

FlowQL: Dependency Management Strategies

At FlowQL, we see projects rot because of dependency fear. Teams stop updating packages because "it might break," leading to security vulnerabilities.

We help you automate your dependency updates (using Renovate or Dependabot) and set up testing pipelines so you can update with confidence, not hope.

Conclusion

Your Action Plan:

1. Try: --legacy-peer-deps first.
2. Check: Does the app build? If yes, great.
3. Override: Use overrides in package.json for permanent fixes.

Don't let a version number stop your feature. [Book a session with FlowQL] to modernize your stack.

---

FAQ

Is --legacy-peer-deps safe to use in production?

Yes, --legacy-peer-deps is generally safe to use if you have verified that the library actually works with your application. It simply disables the strict automated check; it does not change the code that is installed.

What is the difference between --force and --legacy-peer-deps?

--force is a brute-force command that will overwrite existing modules and fetch remote resources even if they exist on disk, potentially causing more instability. --legacy-peer-deps is more precise—it specifically ignores the peer dependency matching algorithm (restoring npm v6 behavior).

Why does React 19 cause so many errors?

React 19 causes many ERESOLVE errors because many popular libraries (like UI kits or form handlers) have peerDependencies set to "react": "^16.0.0 || ^17.0.0 || ^18.0.0". Since "19" is not in that list, npm assumes they are incompatible until the library authors release an update.