BSONVersionError in Mongoose: Ursachen und einfache Lösungen für Node.js-Entwickler

Als erfahrener Node.js-Entwickler mit MongoDB im Backend stoßen Sie irgendwann auf einen Fehler, der scheinbar aus dem Nichts kommt:

BSONVersionError: buffer must be an instance of Buffer or Uint8Array

Dieser tritt plötzlich auf – nach einem Routine-Update, einem Docker-Rebuild oder einem neuen Deployment. Dabei hat sich Ihr Code überhaupt nicht geändert. Doch plötzlich schlagen alle Datenbankabfragen fehl. Was steckt hinter diesem mysteriösen Fehler?

Was verbirgt sich hinter einem BSONVersionError?

BSON (Binary JSON) ist das Binärformat, mit dem MongoDB Dokumente speichert und überträgt. Mongoose nutzt dazu das Paket bson, das meist indirekt über den MongoDB-Treiber eingebunden wird. Ein BSONVersionError entsteht, wenn in Ihrem Projekt zwei unterschiedliche Versionen des `bson`-Pakets gleichzeitig installiert sind. Das führt zu folgendem Problem:

• Eine Version wird direkt oder über eine Abhängigkeit eingebunden, eine weitere über eine andere Komponente (z. B. mongodb oder mongoose).
• Objekte wie ObjectId, die mit einer Version erstellt wurden, werden an Funktionen übergeben, die eine andere Version erwarten.

Neuere bson-Versionen prüfen mit strengeren Mechanismen als nur instanceof. Sie nutzen Tags wie _bsontype oder Symbol-basierte Marker. Wenn also bson@5.x und bson@6.x parallel vorliegen, erkennt eine Version das ObjectId der anderen nicht als gültig – obwohl beide Versionen identisch aussehen.

Wie ich auf den Fehler gestoßen bin

In meinem Fall trat der Fehler nach der Integration eines neuen Pakets auf, das intern einen neueren MongoDB-Treiber benötigte. Mein package.json enthielt eine ältere Mongoose-Version, die auf eine ältere bson-Version verwies. Durch die Abhängigkeitsauflösung von npm wurden beide bson-Versionen in node_modules installiert.

Lokal funktionierte alles problemlos, doch im Deployment brach der Fehler aus, sobald:

• ein ObjectId in einem Teil des Codes mit der neueren bson-Version erstellt wurde und
• dieses ObjectId in einer Mongoose-Abfrage oder nach JSON.stringify/Deserialisierung mit der älteren bson-Version verarbeitet wurde.

Der Fehlertext selbst ist wenig hilfreich. Er spricht nur von ungültigen Puffer-Typen oder BSON-Instanzen – ohne Hinweis darauf, dass das eigentliche Problem eine doppel installierte Abhängigkeit ist.

So diagnostizieren Sie das Problem

Der schnellste Weg zur Bestätigung ist die Überprüfung der installierten bson-Versionen:

npm ls bson

Falls die Ausgabe etwa so aussieht:

├─ bson@6.2.0
└─ mongodb@5.9.0
   └─ bson@5.5.1

ist das der klare Beweis: Zwei Versionen im Abhängigkeitsbaum bedeuten zwei separate Modulinstanzen. Jede hat ihre eigenen Klassen für ObjectId, Binary, Decimal128 und Co.

Ein weiterer Test im Code:

console.log(someId.constructor === mongoose.Types.ObjectId); // false bei Duplikaten

Die Lösung: Drei Wege zur Behebung

Je nach Setup gibt es verschiedene Ansätze, um das Problem zu lösen:

1. Deduplizierung über npm/yarn Overrides

Der sauberste Weg ist die erzwungene Nutzung einer einzigen bson-Version. Fügen Sie in Ihrer package.json folgende Zeile hinzu:

"overrides": {
  "bson": "6.2.0"
}

Für Yarn-Nutzer gilt stattdessen:

"resolutions": {
  "bson": "6.2.0"
}

Führen Sie anschließend einen sauberen Neuaufbau durch:

rm -rf node_modules package-lock.json
npm install
npm ls bson

Prüfen Sie, ob nur noch eine Version angezeigt wird.

2. Gemeinsames Upgrade von Mongoose und MongoDB-Treiber

Manchmal entsteht die Versionen-Divergenz, weil eine veraltete Mongoose-Version einen älteren MongoDB-Treiber nutzt, der nicht zur erwarteten bson-Version passt. Ein Update von Mongoose auf die neueste Hauptversion bringt meist alles in Einklang, da Mongoose intern kompatible Versionen von Treibern und BSON festlegt.

3. Konsistente Nutzung von ObjectId-Quellen

Vermeiden Sie manuelle Importe der ObjectId aus dem bson-Paket:

// ❌ Problem: Führt zu unterschiedlichen Modulinstanzen
import { ObjectId } from "bson";

// ✅ Besser: Nutzung der Mongoose- oder Treiber-Exporte
mongoose.Types.ObjectId;

In Monorepos oder Workspaces kann selbst bei identischen Versionsnummern die Nutzung unterschiedlicher Importpfade zu Instanzen führen, die nicht kompatibel sind.

Fazit: Fehlerbehebung beginnt mit der Abhängigkeitsanalyse

Ein BSONVersionError ist kein Problem Ihrer Daten oder Abfragen – sondern fast immer eine Frage der Abhängigkeitshygiene. Die Fehlermeldungen geben dies nicht direkt preis, sodass Entwickler oft stundenlang Schema, Abfragen oder Dokumente prüfen, bevor sie mit npm ls bson die Ursache in fünf Sekunden finden.

Falls Sie auf diesen Fehler stoßen: Prüfen Sie zuerst die installierten bson-Versionen, bevor Sie tiefer in den Code einsteigen. Ein sauberer Abhängigkeitsbaum spart Zeit und Nerven – und sorgt dafür, dass Ihr MongoDB-Setup reibungslos funktioniert.