NPM Conflicting Peer Dependencies in Windsurf Project
Running npm install in your Windsurf-generated project fails with ERESOLVE peer dependency conflict errors. Cascade added packages that require incompatible versions of shared dependencies, and npm cannot resolve a valid dependency tree.
This is one of the most frustrating issues in Node.js projects because it blocks all progress — you can't install any packages until the conflict is resolved. The error messages are dense and confusing, listing multiple packages and version ranges that seem impossible to untangle.
The problem typically appears after Cascade adds a new package, when upgrading an existing package, or when combining packages that Cascade recommended in different sessions without checking compatibility.
Error Messages You Might See
Common Causes
- React version conflicts — One package requires React 17 while another requires React 18, or a package needs React as a peer dependency but the project uses a different version
- Multiple UI library versions — Cascade installed both an old and new version of the same UI library (e.g., Material UI v4 and v5)
- Outdated packages — Cascade recommended packages with peer dependencies pinned to old versions that conflict with your current stack
- TypeScript version mismatch — Different packages require different TypeScript versions as peer dependencies
- Using --legacy-peer-deps as a band-aid — Previous installs used --legacy-peer-deps to hide conflicts, creating an unstable node_modules that eventually breaks
How to Fix It
- Read the error carefully — npm's ERESOLVE error tells you exactly which packages conflict and what versions they need. Identify the root conflicting dependency
- Check if packages have compatible versions — Often updating one conflicting package to its latest version resolves the peer dependency conflict
- Use npm ls to inspect the tree — Run npm ls [package-name] to see which versions are installed and which packages depend on them
- Remove and reinstall — Delete node_modules and package-lock.json, then run npm install fresh. This often resolves phantom conflicts from corrupted lock files
- Use overrides for stubborn conflicts — Add an "overrides" field in package.json to force a specific version of the conflicting peer dependency
- Avoid --force and --legacy-peer-deps — These flags hide the problem but can cause runtime errors. Only use them as a last resort after understanding the implications
Real developers can help you.
Richard McSorley
Full-Stack Software Engineer with 8+ years building high-performance applications for enterprise clients. Shipped production systems at Walmart (4,000+ stores), Cigna (20M+ users), and Arkansas Blue Cross. 5 patents in retail/supply chain tech. Currently focused on AI integrations, automation tools, and TypeScript-first architectures.
Stanislav Prigodich
15+ years building iOS and web apps at startups and enterprise companies. I want to use that experience to help builders ship real products - when something breaks, I'm here to fix it.
Simon A.
I'm a backend developer building APIs, emulators, and interactive game systems. Professionally, I've developed Java/Spring reporting solutions, managed relational and NoSQL databases, and implemented CI/CD workflows.
Taufan
I’m a product-focused engineer and tech leader who builds scalable systems and turns ideas into production-ready platforms.
Over the past years, I’ve worked across startups and fast-moving teams, leading backend architecture, improving system reliability, and shipping products used by thousands of users. My strength is not just writing code — but connecting product vision, technical execution, and business impact.
Kingsley Omage
Fullstack software engineer passionate about AI Agents, blockchain, LLMs.
Anthony Akpan
Developer with 8 years of experience building softwares fro startups
Matthew Jordan
I've been working at a large software company named Kainos for 2 years, and mainly specialise in Platform Engineering. I regularly enjoy working on software products outside of work, and I'm a huge fan of game development using Unity. I personally enjoy Python & C# in my spare time, but I also specialise in multiple different platform-related technologies from my day job.
Dor Yaloz
SW engineer with 6+ years of experience,
I worked with React/Node/Python
did projects with React+Capacitor.js for ios
Supabase expert
Victor Denisov
Developer
Matthew Butler
Systems Development Engineer @ Amazon Web Services
You don't need to be technical. Just describe what's wrong and a verified developer will handle the rest.
Get HelpFrequently Asked Questions
Is it safe to use --legacy-peer-deps?
It's a temporary workaround, not a fix. --legacy-peer-deps tells npm to ignore peer dependency conflicts, which may cause runtime errors if the packages are truly incompatible. Use it only to unblock yourself while you find a proper resolution.
What are peer dependencies and why do they cause conflicts?
Peer dependencies are packages that a library expects YOU to install (like React for a React component library). Conflicts happen when two libraries expect different versions of the same peer dependency. Only one version can exist in your project.