Mongoose'da BSONVersionError'un Nedeni ve Kalıcı Çözümü

Mongoose ve MongoDB kullanan geliştiricilerin çoğu, beklenmedik bir anda karşılaştıkları şu hatayla karşılaşmıştır:

BSONVersionError: buffer must be an instance of Buffer or Uint8Array

Bu hata genellikle bir npm install komutundan, Docker yeniden inşa işleminden veya yeni bir ortama dağıtımdan hemen sonra ortaya çıkar. Koddaki hiçbir değişiklik olmamasına rağmen, sorgular aniden çalışmayı durdurur. Peki bu hata gerçekte ne anlama gelir ve nasıl çözülür?

BSONVersionError Neden Ortaya Çıkar?

BSON (Binary JSON), MongoDB'nin belgeleri ikili biçimde kodlayıp saklamak için kullandığı standarttır. Mongoose ise bu kodlama ve kod çözme işlemlerini bson paketine (çoğunlukla MongoDB Node.js sürücüsü üzerinden dolaylı olarak dahil edilir) güvenerek gerçekleştirir.

BSONVersionError, bson paketinin farklı sürümlerinin aynı projede bulunmasından kaynaklanır. Bu durum genellikle iki senaryodan birinde meydana gelir:

• Projenizde iki farklı bson sürümü aynı anda yüklüdür (biri doğrudan gereksinim olarak eklenmiş, diğeri mongodb veya mongoose bağımlılığı üzerinden dolaylı olarak dahil edilmiş).
• Farklı bson sürümleri tarafından oluşturulan BSON sınıfları (örneğin ObjectId) birbirlerinin iç yapısını tanımadığı için, geçersiz olarak işaretlenir.

Yeni bson sürümleri, instanceof kontrollerinden daha sıkı olan _bsontype etiketini ve bazen de Sembol tabanlı tanımlayıcıları kullanır. Bu nedenle bson@5.x ve bson@6.x aynı projede bulunursa, bir sürüm tarafından oluşturulan ObjectId'nin diğer sürüm tarafından geçerli olmadığı belirlenir — yüzeyde aynı görünseler bile.

Hatanın Gerçek Yaşanma Senaryosu

Bu hatayla ben de bir Node.js/TypeScript projesinde karşılaştım. Yeni bir paket ekledikten sonra ortaya çıktı. Bu paket, iç bağımlılık olarak daha yeni bir MongoDB sürücüsü gerektiriyordu. Projedeki package.json dosyasında mongoose eski bir bson sürümüne bağlıydı. npm bağımlılık çözümleyicisi, dolaylı olarak iki farklı bson sürümünü node_modules klasörüne yerleştirdi.

Sorun şu şekilde ortaya çıktı:

• Projenin bir kısmında (daha yeni bson üzerinden) oluşturulan bir ObjectId,
• Aynı ObjectId'nin, daha eski bson kopyasını kullanan Mongoose sorgusuna veya JSON.stringify/deserializasyon işlemine aktarılması.

Hata mesajı oldukça yanıltıcıydı — sadece buffer türleri veya geçersiz BSON örnekleriyle ilgili uyarı veriyor, oysa gerçek sorun bağımlılık çatışmasıydı.

Teşhis Yöntemleri

Bu hatanın aslında birden fazla bson sürümünden kaynaklandığını hızlıca doğrulamak için:

npm ls bson

Eğer aşağıdaki gibi bir çıktı alırsanız:

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

Bu, iki farklı bson sürümünün aynı projede bulunduğunun kanıtıdır. Her biri kendi ObjectId, Binary, Decimal128 vb. sınıf tanımlarına sahip iki ayrı modül örneği anlamına gelir.

Çalışma zamanında da doğrulamak mümkündür. Örneğin:

console.log(someId.constructor === mongoose.Types.ObjectId); // false ise çakışma var demektir

Etkili Çözüm Yöntemleri

Bağımlılık çatışmasını çözmek için birkaç yaklaşım mevcut:

1. npm/yarn override kullanarak teke indirgeyin

En temiz çözüm, tüm bağımlılık ağacında tek bir bson sürümünü zorlamaktır. package.json dosyasında aşağıdaki gibi bir tanımlama yapın:

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

(Yarn kullanıcıları: overrides yerine resolutions kullanmalıdır.)

Ardından temiz bir yeniden yükleme yapın:

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

Artık sadece tek bir bson sürümü görünüyorsa, sorun çözülmüştür.

2. Mongoose ve MongoDB sürücüsünü birlikte güncelleyin

Bazen çakışma, eski bir Mongoose sürümünün eski bir MongoDB sürücüsüyle uyumsuzluğundan kaynaklanır. Mongoose'u en son ana sürüme yükseltmek, genellikle dahili olarak uyumlu bson ve sürücü sürümlerine sahip olmanızı sağlar.

3. ObjectId oluştururken tek kaynak kullanın

Eğer aşağıdaki gibi bir kullanımınız varsa:

import { ObjectId } from "bson";

Bunun yerine, her zaman mongoose.Types.ObjectId veya sürücünün kendi çıktısını kullanın. Farklı ithal yoluyla oluşturulan ObjectId'ler, Mongoose'un dahili olarak kullandığı bson modülüyle aynı sınıf örneğine ait olmayabilir — özellikle monorepo veya workspace yapılarında.

Sonuç ve Öneriler

BSONVersionError aslında verilerinizle ilgili bir sorun değildir — bağımlılık yönetiminin ihmalkarlığından kaynaklanır. Hata mesajları "iki tane bson sürümünüz var" demediği için, saatlerce şemanızı, sorgularınızı veya bozulmuş belgelerinizi kontrol edip durabilirsiniz. Oysa npm ls bson komutuyla beş saniyede her şey anlaşılabilir.

Eğer bu hatayla karşılaşırsanız, başka hiçbir yere bakmadan önce ilk olarak npm ls bson komutunu çalıştırın. Bağımlılıklarınızın temiz ve tutarlı olduğundan emin olmak, gelecekteki birçok baş ağrısını önleyecektir.