npm: „ERESOLVE unable to resolve dependency tree“ und Konflikte bei Peer Dependencies

Worum es geht

npm error code ERESOLVE (ab npm 10.6; in npm 7 bis 10.5 npm ERR! code ERESOLVE) stammt vom eigenen Dependency-Resolver von npm. Die npm-Dokumentation zum package.json-Format beschreibt peerDependencies sowie das Feld overrides, mit dem sich diese anpassen lassen. Seit npm 7 werden Peer Dependencies automatisch installiert, statt nur eine Warnung auszugeben. npm muss daher für jedes Paket eine einzige Version finden, die alle Peer-Bereiche im gesamten Baum gleichzeitig erfüllt. ERESOLVE bedeutet, dass dies nicht gelungen ist: Das eigene Projekt oder eine direkte Abhängigkeit deklariert für ein Paket einen peerDependencies-Bereich, und eine andere Abhängigkeit im Baum benötigt eine Version ausserhalb dieses Bereichs. Konflikte tief im Baum werden standardmässig nur mit der Warnung ERESOLVE overriding peer dependency aufgelöst; mit --strict-peer-deps führen auch sie zu einem Fehler.

Warum es wichtig ist

Die Fehlermeldung weist nicht für sich genommen auf ein defektes Paket hin. Sie benennt einen tatsächlichen Konflikt zwischen Anforderungen, den es schon vor npm 7 gab, nur wurde er stillschweigend hingenommen. Wer ihn umgeht, ohne zu verstehen, welche zwei Anforderungen kollidieren, riskiert einen Abhängigkeitsbaum, der zur Laufzeit nicht erfüllt, was eines der Pakete erwartet, obwohl die Installation selbst gelingt.

So wird es angewendet

• Diagnose: den gesamten Fehlerblock lesen, nicht nur die erste Zeile. npm gibt Found: x@version aus (die aktuell aufgelöste Version), gefolgt von einer oder mehreren Zeilen Could not resolve dependency: peer x@"range" from y@version. Diese nennen genau, welches Paket welchen Bereich verlangt und von wo. npm ls <package> --all zeigt anschliessend alle Stellen im Baum, die davon abhängen.
• Lösungen, von der am wenigsten bis zur am stärksten eingreifenden:
  1. Die betroffenen Pakete auf Versionen aktualisieren, deren Peer-Bereiche sich tatsächlich überschneiden. Das ist oft die eigentliche Lösung, da der Konflikt häufig darauf beruht, dass eine Abhängigkeit den anderen wirklich hinterherhinkt.
  2. Ist der Peer-Bereich eines Pakets schlicht strenger als nötig (er deklariert einen engen Bereich, funktioniert aber bekanntermassen mit der verwendeten neueren Major-Version), lässt sich genau diese verschachtelte Auflösung über das Feld overrides in package.json festlegen (npm 8.3+). Es ist zusammen mit peerDependencies dokumentiert. Das ist besser, als die Prüfung für den ganzen Baum aufzuweichen.
  3. Unsichere Notlösung: npm install --legacy-peer-deps, als Option von npm install dokumentiert, stellt das Verhalten von npm 6 wieder her, Peers weder automatisch zu installieren noch strikt zu prüfen. Das funktioniert, doch npm überprüft dann die Peer-Erwartungen im gesamten Baum nicht mehr, nicht nur beim vorliegenden Konflikt.
  4. npm install --force geht noch weiter und installiert auch über andere von npm erkannte Konflikte hinweg. Es ist als einmaliger letzter Ausweg zu betrachten und nicht als Standard in der CI einzuchecken, da der resultierende Baum zur Laufzeit möglicherweise nicht erfüllt, was ein Paket erwartet.
• Keine Lösung: node_modules und package-lock.json löschen und neu installieren. Wenn die deklarierten Bereiche im Konflikt stehen, scheitert npm auf dieselbe Weise, und die im Lockfile festgehaltenen Versionen gehen verloren.

Stolpersteine

• --force verwenden, bevor geklärt ist, welche zwei Pakete tatsächlich in Konflikt stehen. Das muss dann ohnehin diagnostiziert werden, sobald zur Laufzeit etwas nicht funktioniert.
• --legacy-peer-deps als dauerhaftes CI-Flag festschreiben, wodurch sich danach unbemerkt neue, davon unabhängige Peer-Konflikte ansammeln können.