What causes "Negative binary type element size found for subtype 0x02" in mongodb/node-mongodb-native?

Validate the source of the binary data; if you wrote it, ensure subtype 0x02 payloads include the correct 4-byte inner length prefix.

mongodb/node-mongodb-native · error · BSONError

Negative binary type element size found for subtype 0x02

Error message

Negative binary type element size found for subtype 0x02

What it means

Thrown while decoding a BSON binary element of subtype 0x02 (old binary) when the embedded subType2BinarySize (a 4-byte little-endian int32 read after the subtype byte) is negative. A negative length is impossible for valid BSON and indicates corruption or malformed data. Surfaced as a BSONError from the on-demand BSON decoder used to parse server responses lazily.

Source

Thrown at src/cmap/wire_protocol/on_demand/document.ts:204

        return NumberUtils.getInt32LE(this.bson, offset);
      case BSONType.long:
        return NumberUtils.getBigInt64LE(this.bson, offset);
      case BSONType.bool:
        return Boolean(this.bson[offset]);
      case BSONType.objectId:
        return new ObjectId(this.bson.subarray(offset, offset + 12));
      case BSONType.timestamp:
        return new Timestamp(NumberUtils.getBigInt64LE(this.bson, offset));
      case BSONType.string:
        return ByteUtils.toUTF8(this.bson, offset + 4, offset + length - 1, false);
      case BSONType.binData: {
        const totalBinarySize = NumberUtils.getInt32LE(this.bson, offset);
        const subType = this.bson[offset + 4];

        if (subType === 2) {
          const subType2BinarySize = NumberUtils.getInt32LE(this.bson, offset + 1 + 4);
          if (subType2BinarySize < 0)
            throw new BSONError('Negative binary type element size found for subtype 0x02');
          if (subType2BinarySize > totalBinarySize - 4)
            throw new BSONError('Binary type with subtype 0x02 contains too long binary size');
          if (subType2BinarySize < totalBinarySize - 4)
            throw new BSONError('Binary type with subtype 0x02 contains too short binary size');
          return new Binary(
            this.bson.subarray(offset + 1 + 4 + 4, offset + 1 + 4 + 4 + subType2BinarySize),
            2
          );
        }

        return new Binary(
          this.bson.subarray(offset + 1 + 4, offset + 1 + 4 + totalBinarySize),
          subType
        );
      }
      case BSONType.date:
        // Pretend this is correct.
        return new Date(Number(NumberUtils.getBigInt64LE(this.bson, offset)));

View on GitHub (pinned to 3366c21a63)

Solutions

Validate the source of the binary data; if you wrote it, ensure subtype 0x02 payloads include the correct 4-byte inner length prefix.
Check for network/proxy corruption by comparing server-side and client-side bytes.
If reading from a non-MongoDB BSON producer, ensure it emits spec-compliant subtype-0x02 binary.
Report a BSON issue in js-bson if the data is known-good and the error still occurs on the current version.

Defensive patterns

Strategy: try-catch

Try / catch

import { BSONError } from 'bson';
try {
  await collection.findOne({ _id });
} catch (err) {
  if (err instanceof BSONError && /Negative binary type element size/.test(err.message)) {
    // data corruption; re-read or quarantine the document
  }
  throw err;
}

Prevention

Validate binary payloads at write time using the official bson Binary type.
Audit non-MongoDB BSON producers for subtype-0x02 length correctness.
Check for network/proxy corruption on persistent decode errors.

When it happens

Trigger: OnDemandDocument.toJSValue() reads a binData element whose subtype byte is 2, then reads the inner binary size as int32; if that value is < 0 the error throws. Triggered when parsing any server response (cursor documents, command results) containing a subtype-0x02 binary field with a corrupt length prefix. Common when the document was hand-constructed incorrectly or corrupted on the wire.

Common situations: Storing/receiving binary data with subtype 0x02 from a source that wrote the length incorrectly. Wire corruption. Interop with another BSON producer that emits malformed old-binary elements. Parsing a truncated buffer.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/2bfd018e0aba3f98.json. Report an issue: GitHub.