mongodb/node-mongodb-native · error · BSONError

Binary type with subtype 0x02 contains too short binary size

Error message

Binary type with subtype 0x02 contains too short binary size

What it means

Thrown while decoding a BSON binary subtype 0x02 element when the inner subType2BinarySize is smaller than totalBinarySize - 4 (the inner payload should exactly fill the outer payload minus the 4-byte prefix). Per BSON subtype-0x02 semantics the inner length must equal totalBinarySize - 4; a smaller value is a validity violation. Surfaced as BSONError by the on-demand decoder.

Source

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

        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:
        return new OnDemandDocument(this.bson, offset);
      case BSONType.array:

View on GitHub (pinned to 3366c21a63)

Solutions

1. Inspect and correct the source binary data so inner length equals totalBinarySize - 4 for subtype 0x02.
2. Re-read the document from the server to rule out in-flight corruption.
3. Upgrade bson/driver for decoder robustness.
4. If producing this BSON yourself, use the official bson library's Binary type to guarantee correct sizing.

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

When it happens

Trigger: toJSValue() finds subType2BinarySize < totalBinarySize - 4, i.e. leftover bytes in the outer binary payload that the inner length does not account for. Triggered when a subtype-0x02 binary field is malformed (inner length too small for the outer payload). Same shape of corruption as 131 but in the opposite direction.

Common situations: Malformed binary written by a non-compliant BSON producer, buffer truncation/padding, or an upstream slicing bug. Interop issues with legacy BSON libraries that padded or mis-sized old-binary fields.

Related errors

• Negative binary type element size found for subtype 0x02
• Binary type with subtype 0x02 contains too long 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/cb5f83f8d04f1b21.json. Report an issue: GitHub.