mongodb/node-mongodb-native · error · BSONError

BSON element " " is missing

Error message

BSON element "${name}" is missing

What it means

Thrown by OnDemandDocument.get when an element with the requested name does not exist AND the caller passed required=true. It is a BSONError indicating a mandatory field is absent from the BSON document. Because OnDemandDocument is @internal, this fires inside driver code that asserts a field the server is contractually expected to return.

Solutions

1. Ensure the server version meets the driver's minimum supported version.
2. Upgrade the driver and server to compatible releases.
3. Remove any intermediate that alters server responses.
4. Report the unexpected response shape to the driver team.

try {
  await client.db().admin().command({ hello: 1 });
} catch (e) {
  if (e instanceof MongoUnexpectedServerResponseError) {
  }
}

When it happens

Trigger: Fires at src/cmap/wire_protocol/on_demand/document.ts:286 when getElement(name) returns null and required is true. Reachable through any internal call site using get(..., true), typically while parsing SDAM, command, or cursor responses.

Common situations: Server version that omits a field the driver expects (version skew); a proxy stripping fields; a corrupted response; pointing a newer driver at a much older server. When surfaced through MongoDBResponse.get it is wrapped as MongoUnexpectedServerResponseError (see error 149).

Related errors

• Unsupported BSON type
• Binary type with subtype 0x02 contains too long binary size
• Binary type with subtype 0x02 contains too short binary size
• ${cause.message}
• Negative binary type element size found for subtype 0x02

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

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