mongodb/node-mongodb-native · warning · MongoRuntimeError

A query document must be specified for query

Error message

A query document must be specified for query

What it means

Thrown as a MongoRuntimeError in the OpQueryRequest constructor when the query document is null or undefined. OpQueryRequest wraps the legacy OP_QUERY wire protocol message. Like [105], this is an internal invariant — the driver never intentionally builds a query with no body.

Solutions

1. File a driver bug report with the full stack trace
2. In tests, ensure a non-null query document is passed when constructing OpQueryRequest
3. Do not call the @internal OpQueryRequest constructor directly

function isNonNullQuery(q: unknown): q is Record<string, unknown> {
  return q != null && typeof q === 'object';
}

When it happens

Trigger: Internal construction of OpQueryRequest with a null/undefined query argument. Not reachable via the public API; indicates an internal driver error or a malformed mock in tests.

Common situations: Driver bug, broken test fixture, or direct internal API misuse.

Related errors

• Database name must be a string for a query
• Argument "size" must be a non-negative number
• Query document must be specified for query
• A collection name must be determined before getMore
• A collection name must be determined before killCursors

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

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