npm ERESOLVE: Abhängigkeitskonflikte beim Update lösen
Kurz gesagt: Die Meldung npm ERR! code ERESOLVE mit „unable to resolve dependency tree“ bedeutet, dass zwei Pakete in Ihrem Projekt unterschiedliche, nicht vereinbare Versionen eines dritten Pakets verlangen, meist über sogenannte Peer-Abhängigkeiten. Typisch ist das nach einem Update von React, Vue, ESLint oder einem Build-Werkzeug, wenn ein Plugin noch die alte Hauptversion erwartet. Der schnelle Ausweg --legacy-peer-deps funktioniert oft, verschiebt das Problem aber nur. Besser ist es, den Konflikt zu lesen, das passende Paket zu aktualisieren oder gezielt zu überschreiben und das Ergebnis in der Lockfile festzuhalten. Dieser Artikel zeigt den Weg Schritt für Schritt.
Was hinter ERESOLVE steckt
Viele Erweiterungen für Frameworks bringen das Framework nicht selbst mit, sondern erwarten, dass Ihr Projekt es bereitstellt. Das drücken sie über peerDependencies in ihrer package.json aus, etwa „funktioniert mit Version 2.x des Hauptpakets“. Die npm-Dokumentation zur package.json erklärt, dass Peer-Abhängigkeiten in den npm-Versionen 3 bis 6 nicht automatisch installiert wurden und nur eine Warnung auslösten. Seit npm 7 werden sie standardmäßig installiert. Wenn ein weiteres Plugin eine widersprüchliche Anforderung hat, kann die Installation daher fehlschlagen.
Genau das ist ERESOLVE: npm findet keinen Abhängigkeitsbaum, in dem alle Bedingungen gleichzeitig erfüllt sind. Das ist kein Defekt von npm, sondern eine ehrliche Auskunft, dass mindestens ein Paket offiziell nicht zu den anderen passt.
Die Fehlermeldung lesen
Die Ausgabe wirkt lang, enthält aber drei entscheidende Zeilen:
- „While resolving“ nennt das Paket, das gerade eingeordnet werden sollte.
- „Found“ zeigt, welche Version eines Pakets bereits im Baum steht.
- „Could not resolve dependency“ und „peer … from …“ nennen die Anforderung, die nicht passt, und wer sie stellt.
Ein Beispielauszug (Beispiel zur Veranschaulichung):
While resolving: shop-frontend@1.4.0
Found: react@19.0.0
Could not resolve dependency:
peer react@"^17.0.0 || ^18.0.0" from datepicker-plugin@3.2.1
Hier ist die Lage klar: Das Datumsauswahl-Plugin erklärt sich nur mit React 17 und 18 kompatibel, Ihr Projekt nutzt aber bereits 19. Zusätzlich hilft npm explain paketname, um zu sehen, warum ein Paket überhaupt im Projekt ist und wer es anfordert.
Lösungswege in sinnvoller Reihenfolge
1. Das blockierende Paket aktualisieren. Prüfen Sie, ob es eine neuere Version gibt, die die neue Hauptversion unterstützt. npm view paketname peerDependencies zeigt die Anforderungen der aktuellsten Version. Oft ist das Problem damit gelöst.
2. Das Update des Hauptpakets verschieben. Gibt es noch keine kompatible Version des Plugins, ist es manchmal klüger, beim bisherigen Framework zu bleiben, bis die Erweiterungen nachgezogen haben.
3. Das Plugin ersetzen. Wird ein Paket nicht mehr gepflegt, lohnt der Blick nach einer Alternative oder einem gepflegten Fork.
4. Gezielt überschreiben. Die package.json kennt das Feld overrides. Laut npm-Dokumentation ist es für Fälle gedacht, in denen Sie Abhängigkeiten Ihrer Abhängigkeiten gezielt ändern müssen, etwa um eine Version mit bekannter Sicherheitslücke zu ersetzen, einen Fork einzusetzen oder überall dieselbe Version zu erzwingen. Ein Override ist eine bewusste Aussage „ich übernehme die Verantwortung, dass das zusammen funktioniert“. Testen Sie danach gründlich.
5. Als letzter Ausweg: legacy-peer-deps. Die npm-Dokumentation beschreibt legacy-peer-deps so, dass npm Peer-Abhängigkeiten beim Aufbau des Baums vollständig ignoriert, wie in den Versionen 3 bis 6. Das ist als Weg gedacht, bei kollidierenden, zu strengen Anforderungen weiterzukommen. Das Risiko: Pakete laufen dann mit Versionen, für die sie nie getestet wurden, und Fehler zeigen sich erst später im Betrieb.
Warum --force selten die richtige Antwort ist
Neben --legacy-peer-deps wird oft --force empfohlen. Es zwingt npm, trotz Konflikten zu installieren, und kann dabei unerwartete Versionen einsetzen. Für eine schnelle Probe lokal mag das gehen, in einer Build-Pipeline oder auf dem Rechner einer Kollegin führt es leicht zu einem anderen Baum als bei Ihnen. Wenn Sie eine Ausnahme brauchen, ist ein dokumentierter Override nachvollziehbarer.
Das Ergebnis festhalten
Egal welchen Weg Sie wählen: Committen Sie die aktualisierte package-lock.json. Nur so installiert die nächste Person und der Build-Server denselben Baum. Wenn Sie legacy-peer-deps dauerhaft brauchen, legen Sie es in einer projektbezogenen .npmrc fest, statt es jedem einzeln mitzuteilen, und schreiben Sie in die Projektnotizen, warum. So weiß das Team, dass dies eine Ausnahme ist, die bei der nächsten Gelegenheit wieder entfernt werden soll.
Installieren Sie im Build-Prozess mit npm ci. Der Befehl nutzt die Lockfile genau so, wie sie ist, und bricht ab, wenn sie nicht zur package.json passt. Unterschiede zwischen Entwicklerrechner und Server fallen dadurch früh auf.
Vorbeugen: Updates in kleinen Schritten
Die meisten ERESOLVE-Abbrüche entstehen, wenn ein Projekt lange nicht aktualisiert wurde und dann mehrere Hauptversionen auf einmal springen soll. Planen Sie Updates deshalb regelmäßig und in kleinen Schritten, etwa einmal im Monat für kleinere Versionen und gezielt für einzelne Hauptversionen. npm outdated zeigt, welche Pakete hinterherhinken und wie groß der Abstand ist.
Hilfreich ist auch eine kurze Liste der Plugins, die eng an das Framework gebunden sind, also Komponentenbibliotheken, Formular-Erweiterungen oder Testwerkzeuge. Bevor Sie das Framework anheben, prüfen Sie bei genau diesen Paketen, ob sie die neue Version schon unterstützen. Das kostet wenige Minuten und erspart Ihnen einen halben Tag mit verknoteten Abhängigkeiten. Arbeiten Sie dabei in einem eigenen Zweig der Versionsverwaltung, damit die laufende Website unberührt bleibt, bis alles getestet ist.
Beispiel zur Veranschaulichung
Ein Kölner Kursanbieter (Beispiel zur Veranschaulichung) lässt die Buchungsseite auf eine neue Framework-Version heben. npm install scheitert mit ERESOLVE wegen eines Kalender-Plugins. Die Agentur liest die Meldung, findet eine neue Hauptversion des Plugins mit passender Peer-Anforderung und aktualisiert es. Ein zweites, nicht mehr gepflegtes Paket ersetzt sie durch eine kleine eigene Komponente. Die neue Lockfile wird committet, der Build nutzt npm ci. Ein dauerhaftes legacy-peer-deps ist nicht nötig.
Typische Fehler
- Sofort
--forceoder--legacy-peer-depssetzen, ohne die Meldung zu lesen. - Die Lockfile nicht committen, sodass jeder einen anderen Baum bekommt.
- Overrides ohne Kommentar und ohne Tests einbauen.
- Große Updates mehrerer Hauptversionen auf einmal, sodass Konflikte sich überlagern.
- Nicht gepflegte Plugins mitschleppen, die jede Aktualisierung blockieren.
Häufige Fragen
Ist ERESOLVE ein Fehler in npm?
Nein. npm meldet, dass die erklärten Anforderungen der Pakete nicht gleichzeitig erfüllbar sind.
Darf ich legacy-peer-deps dauerhaft nutzen?
Technisch ja, aber Sie verzichten damit auf eine wichtige Prüfung. Nutzen Sie es als dokumentierte Übergangslösung.
Was ist der Unterschied zwischen overrides und legacy-peer-deps?
Ein Override ändert gezielt eine bestimmte Abhängigkeit. legacy-peer-deps ignoriert Peer-Abhängigkeiten im ganzen Projekt.
Warum funktioniert die Installation bei mir, aber nicht im Build?
Häufig wegen unterschiedlicher npm-Versionen oder einer fehlenden Lockfile. Gleichen Sie die Versionen an und nutzen Sie npm ci.
Wenn Ihr Projekt bei Updates immer wieder an Abhängigkeitskonflikten hängen bleibt, sortieren wir die Pakete gern gemeinsam mit Ihnen: Update-Problem schildern.