mongodb/node-mongodb-native · error · RangeError

OP_REPLY numberReturned is an invalid array length ${this.nu

Error message

OP_REPLY numberReturned is an invalid array length ${this.numberReturned}

What it means

Thrown by OpReply.parse() (commands.ts:381) as a RangeError when the OP_REPLY message's numberReturned field is negative or exceeds the maximum representable unsigned 32-bit value. numberReturned tells the driver how many BSON documents follow in the reply; an out-of-range value would cause either an infinite/huge allocation or a negative loop bound when parsing the body.

Source

Thrown at src/cmap/commands.ts:381

    return this.parsed;
  }

  parse(): Uint8Array {
    // Don't parse again if not needed
    if (this.parsed) return this.sections[0];

    // Position within OP_REPLY at which documents start
    // (See https://www.mongodb.com/docs/manual/reference/mongodb-wire-protocol/#wire-op-reply)
    this.index = 20;

    // Read the message body
    this.responseFlags = readInt32LE(this.data, 0);
    this.cursorId = new BSON.Long(readInt32LE(this.data, 4), readInt32LE(this.data, 8));
    this.startingFrom = readInt32LE(this.data, 12);
    this.numberReturned = readInt32LE(this.data, 16);

    if (this.numberReturned < 0 || this.numberReturned > 2 ** 32 - 1) {
      throw new RangeError(
        `OP_REPLY numberReturned is an invalid array length ${this.numberReturned}`
      );
    }

    this.cursorNotFound = (this.responseFlags & CURSOR_NOT_FOUND) !== 0;
    this.queryFailure = (this.responseFlags & QUERY_FAILURE) !== 0;
    this.shardConfigStale = (this.responseFlags & SHARD_CONFIG_STALE) !== 0;
    this.awaitCapable = (this.responseFlags & AWAIT_CAPABLE) !== 0;

    // Parse Body
    for (let i = 0; i < this.numberReturned; i++) {
      const bsonSize =
        this.data[this.index] |
        (this.data[this.index + 1] << 8) |
        (this.data[this.index + 2] << 16) |
        (this.data[this.index + 3] << 24);

      const section = this.data.subarray(this.index, this.index + bsonSize);

View on GitHub (pinned to 3366c21a63)

Solutions

Upgrade the server to 3.2+ which uses OP_MSG instead of OP_REPLY
Inspect the network path for a corrupting proxy or load balancer
If using a MongoDB-compatible emulator, ensure it encodes numberReturned correctly
Report as a driver/server bug with a packet capture if it reproduces against genuine MongoDB

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await client.connect();
} catch (e) {
  if (e instanceof RangeError && /numberReturned/i.test(e.message)) {
    // malformed OP_REPLY - verify server/proxy integrity, upgrade server
  }
  throw e;
}

Prevention

Use MongoDB 3.2+ which uses OP_MSG, avoiding OP_REPLY
Inspect proxies/load balancers on the network path
Avoid MongoDB-compatible servers that produce malformed frames

When it happens

Trigger: Server (or intermediary) sent an OP_REPLY whose 4-byte numberReturned field at offset 16 decodes to < 0 or > 2^32-1. OP_REPLY is the legacy wire protocol used by pre-3.2 servers and a few internal paths; a malformed value indicates corruption, a buggy server, or a misbehaving proxy.

Common situations: Network corruption truncating or garbling a reply; a non-genuine MongoDB-compatible server/proxy producing malformed OP_REPLY frames; very old server (< 3.2) with a bug. Modern deployments use OP_MSG and never hit this code path.

Related errors

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