mongodb/node-mongodb-native · error · BSONError

Binary type with subtype 0x02 contains too long binary size

Error message

Binary type with subtype 0x02 contains too long binary size

What it means

Thrown while decoding a BSON binary subtype 0x02 element when the inner subType2BinarySize is larger than totalBinarySize - 4 (the inner payload cannot be larger than the outer binary payload minus its own 4-byte length prefix). This is a structural BSON validity violation indicating corrupt or malformed data. Surfaced as BSONError by the on-demand decoder.

Source

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

        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)));

      case BSONType.object:

View on GitHub (pinned to 3366c21a63)

Solutions

1. Verify the integrity of the binary data at the source (re-read from the database, compare checksums).
2. Ensure any custom BSON producer writes consistent outer/inner lengths for subtype 0x02.
3. Upgrade bson/driver to pick up decoder fixes.
4. If the data is legitimately malformed, sanitize or rewrite it server-side before reading.

import { BSONError } from 'bson';
try {
  await collection.findOne({ _id });
} catch (err) {
  if (err instanceof BSONError && /too long binary size/.test(err.message)) {
    // subtype 0x02 inner size exceeds outer payload; quarantine document
  }
  throw err;
}

When it happens

Trigger: toJSValue() computes subType2BinarySize and totalBinarySize from the element; if subType2BinarySize > totalBinarySize - 4 the declared inner length overflows the available bytes. Happens when a subtype-0x02 binary field's outer and inner length fields are inconsistent, e.g. truncated or hand-mangled data, or a buffer slice computed incorrectly upstream.

Common situations: Corrupt binary payloads from another BSON producer, truncated wire messages, or a driver/bson bug in versions with an off-by-one in size computation. Interop with data written by an old/buggy BSON library.

Related errors

• Negative binary type element size found for subtype 0x02
• Binary type with subtype 0x02 contains too short binary size
• Unsupported BSON type: ${as}
• BSON element "${name}" is missing
• Document is larger than the maximum size ${this.s.maxBsonObj

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