mongodb/node-mongodb-native · error · MongoRuntimeError

A query document must be specified for query

Error message

A query document must be specified for query

What it means

Thrown by the OpQueryRequest constructor (commands.ts:98) as a MongoRuntimeError when the query document is null or undefined. The OP_QUERY message must contain a query body to send to the server; an empty one is rejected at construction. Internal invariant - the public API always supplies a query document.

Source

Thrown at src/cmap/commands.ts:98

  oplogReplay: boolean;
  noCursorTimeout: boolean;
  awaitData: boolean;
  exhaust: boolean;
  partial: boolean;
  /** moreToCome is an OP_MSG only concept */
  moreToCome = false;
  databaseName: string;
  query: Document;

  constructor(databaseName: string, query: Document, options: OpQueryOptions) {
    // Basic options needed to be passed in
    // TODO(NODE-3483): Replace with MongoCommandError
    const ns = `${databaseName}.$cmd`;
    if (typeof databaseName !== 'string') {
      throw new MongoRuntimeError('Database name must be a string for a query');
    }
    // TODO(NODE-3483): Replace with MongoCommandError
    if (query == null) throw new MongoRuntimeError('A query document must be specified for query');

    // Validate that we are not passing 0x00 in the collection name
    if (ns.indexOf('\x00') !== -1) {
      // TODO(NODE-3483): Use MongoNamespace static method
      throw new MongoRuntimeError('Namespace cannot contain a null character');
    }

    // Basic optionsa
    this.databaseName = databaseName;
    this.query = query;
    this.ns = ns;

    // Additional options
    this.numberToSkip = options.numberToSkip || 0;
    this.numberToReturn = options.numberToReturn || 0;
    this.returnFieldSelector = options.returnFieldSelector || undefined;
    this.requestId = options.requestId ?? OpQueryRequest.getRequestId();

View on GitHub (pinned to 3366c21a63)

Solutions

1. Report as a driver bug with the operation and version that triggered it
2. Use the public Collection/Db APIs rather than constructing OpQueryRequest manually
3. If subclassing, always pass a non-null query document

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoRuntimeError && /query document must be specified/i.test(e.message)) {
    // internal bug - report to driver maintainers
  }
  throw e;
}

When it happens

Trigger: Internal code calling new OpQueryRequest(db, null, options) or new OpQueryRequest(db, undefined, options). Reachable only through driver internals or a non-standard subclass.

Common situations: Driver defect where a command builder returned null; extension code that forgot to pass a query document.

Related errors

• Database name must be a string for a query
• Query document must be specified for query
• No workflow provided to the OIDC auth provider.
• Namespace cannot contain a null character
• Argument "size" must be a non-negative number

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