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 when decoding a BSON Binary subtype 0x02 element whose declared inner length exceeds totalBinarySize - 4 (the space left after the inner-length prefix). The element is structurally impossible, so the parser refuses it with a BSONError. This is a malformed-BSON guard inside the on-demand document reader.

Solutions

1. Retry to rule out transient corruption.
2. Remove proxies/inspectors on the connection path.
3. Update server and driver; capture and report the offending payload if it persists.

try {
  await coll.findOne({_id:1});
} catch (e) {
  if (e instanceof BSONError && /too long binary size/.test(e.message)) {
  }
}

When it happens

Trigger: Fires at src/cmap/wire_protocol/on_demand/document.ts:206 during toJSValue for a binData/subtype-2 element when subType2BinarySize > totalBinarySize - 4. Encountered while reading any server response or OnDemandDocument containing such a corrupted binary field.

Common situations: Truncated or corrupted wire response; a faulty proxy; a server-side serialization bug; BSON produced by a non-conforming writer. Not triggered by normal application data.

Related errors

• Binary type with subtype 0x02 contains too short binary size
• Negative binary type element size found for subtype 0x02
• BSON element " " is missing
• Message body and message header must be the same length
• OP_MSG Payload Type 1 detected unsupported protocol

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/33e6a3dd89431baf. Report an issue: GitHub.

Appendix: 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 dce7939f86)