mongodb/node-mongodb-native · error · MongoUnexpectedServerResponseError

${cause.message}

Error message

${cause.message}

What it means

MongoDBResponse.get wraps any BSONError thrown by the underlying OnDemandDocument.get and re-throws it as a MongoUnexpectedServerResponseError, preserving the original as `cause`. The message is the wrapped error's message. It signals that a server response did not contain a field, or contained a wrong-typed field, that the driver requires to continue. This is the user-visible form of errors 146/147 when responses are parsed.

Source

Thrown at src/cmap/wire_protocol/responses.ts:95

  public override get<const T extends keyof JSTypeOf>(
    name: string | number,
    as: T,
    required?: false
  ): JSTypeOf[T] | null;
  public override get<const T extends keyof JSTypeOf>(
    name: string | number,
    as: T,
    required: true
  ): JSTypeOf[T];
  public override get<const T extends keyof JSTypeOf>(
    name: string | number,
    as: T,
    required?: boolean
  ): JSTypeOf[T] | null {
    try {
      return super.get(name, as, required);
    } catch (cause) {
      throw new MongoUnexpectedServerResponseError(cause.message, { cause });
    }
  }

  static is(value: unknown): value is MongoDBResponse {
    return value instanceof MongoDBResponse;
  }

  static make(bson: Uint8Array) {
    const elements = parseToElementsToArray(bson, 0);
    const isError = isErrorResponse(bson, elements);
    return isError
      ? new MongoDBResponse(bson, 0, false, elements)
      : new this(bson, 0, false, elements);
  }

  // {ok:1}
  static empty = new MongoDBResponse(new Uint8Array([13, 0, 0, 0, 16, 111, 107, 0, 1, 0, 0, 0, 0]));

View on GitHub (pinned to dce7939f86)

Solutions

1. Check the MongoDB server version meets the driver's minimum supported version (see driver compatibility matrix).
2. Upgrade both driver and server to compatible, current releases.
3. Connect directly to mongod/mongos, bypassing proxies.
4. If it persists, capture the failing command/response and file a driver issue with versions of both sides.

try {
  await collection.find({}).toArray();
} catch (error) {
  if (error instanceof MongoUnexpectedServerResponseError) {
  }
}

When it happens

Trigger: Fires at src/cmap/wire_protocol/responses.ts:95 whenever MongoDBResponse.get(name, as, required) calls super.get and that throws. Common during SDAM hello/isMaster parsing, command response parsing, or any internal required-field read on a server BSON reply.

Common situations: Connecting a newer driver to an older, unsupported MongoDB server; a proxy/load-balancer rewriting or truncating responses; a server bug omitting a required field; network corruption. Frequently seen after a server downgrade or during a rolling upgrade mismatch.

Related errors

• BSON element "${name}" is missing
• Raw operations are not allowed
• Invalid server nonce length ${serverNonce.length}, expected
• Server nonce does not begin with client nonce
• Server returned an invalid host: "${host}"

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