mongodb/node-mongodb-native · error · BSONError

BSON element "${name}" is missing

Error message

BSON element "${name}" is missing

What it means

Thrown by OnDemandDocument.get(name, as, required) when required is true and no element with the given name exists in the document (getElement returned null). This is the on-demand BSON decoder's way of enforcing a required field. Surfaced as BSONError. It indicates the parsed BSON document is missing a field the caller declared mandatory.

Source

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

    required?: boolean
  ): JSTypeOf[T] | null;

  /** `required` will make `get` throw if name does not exist or is null/undefined */
  public get<const T extends keyof JSTypeOf>(
    name: string | number,
    as: T,
    required: true
  ): JSTypeOf[T];

  public get<const T extends keyof JSTypeOf>(
    name: string | number,
    as: T,
    required?: boolean
  ): JSTypeOf[T] | null {
    const element = this.getElement(name);
    if (element == null) {
      if (required === true) {
        throw new BSONError(`BSON element "${name}" is missing`);
      } else {
        return null;
      }
    }

    if (element.value == null) {
      const value = this.toJSValue(element.element, as);
      if (value == null) {
        if (required === true) {
          throw new BSONError(`BSON element "${name}" is missing`);
        } else {
          return null;
        }
      }
      // It is important to never store null
      element.value = value;
    }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Inspect the named field in the error; confirm the server is a genuine MongoDB instance returning the expected response shape.
2. Upgrade the driver and server to compatible versions.
3. Remove any intermediary that may rewrite server responses.
4. If the field is legitimately optional, the caller (driver internals) must be fixed; report a driver bug.

import { BSONError } from 'bson';
try {
  await cursor.next();
} catch (err) {
  if (err instanceof BSONError && /BSON element .* is missing/.test(err.message)) {
    // a mandatory field is absent from the server response; check server/proxy
  }
  throw err;
}

When it happens

Trigger: get('field', BSONType.x, true) is called on an OnDemandDocument that has no element named 'field'. In the driver this is used internally to read mandatory fields from server responses (cursor.id, ns, batch, etc.). Triggered when a server response is missing a field the driver expects, e.g. a malformed cursor document without an id.

Common situations: Server responses that omit a mandatory field due to a server bug or version mismatch. Talking to a non-MongoDB server that returns a partially-shaped response. Proxy/intermediary that strips fields. The error message names the missing field to aid diagnosis.

Related errors

• Negative binary type element size found for subtype 0x02
• Binary type with subtype 0x02 contains too long binary size
• Binary type with subtype 0x02 contains too short binary size
• Unsupported BSON type: ${as}
• 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/10bef45c7abf8fbb.json. Report an issue: GitHub.