mongodb/node-mongodb-native · warning · MongoInvalidArgumentError

Query document must be specified for query

Error message

Query document must be specified for query

What it means

Thrown as a MongoInvalidArgumentError in the OpMsgRequest constructor when the command document is null or undefined. OpMsgRequest is the modern (MongoDB 3.6+) OP_MSG wire protocol request. This is an internal invariant — the driver never intentionally builds an empty command.

Solutions

1. Report a driver bug with the stack trace if hit in production
2. In custom operation code, ensure the command document is always a non-null object
3. Avoid directly constructing the @internal OpMsgRequest class

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

When it happens

Trigger: Internal construction of OpMsgRequest with a null/undefined command. Not reachable from the public API; would only occur from a driver bug, a faulty operation implementation, or a broken test mock.

Common situations: Driver bug, a custom operation subclass that returns null from its command builder, or test code that directly instantiates OpMsgRequest without a command.

Related errors

• A query document must be specified for query
• Argument "size" must be a non-negative number
• Database name must be a string for a query
• OP_MSG Payload Type 1 detected unsupported protocol
• A collection name must be determined before getMore

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

Appendix: source

Thrown at src/cmap/commands.ts:537

/** @internal */
export class OpMsgRequest {
  requestId: number;
  serializeFunctions: boolean;
  ignoreUndefined: boolean;
  checkKeys: boolean;
  maxBsonSize: number;
  checksumPresent: boolean;
  moreToCome: boolean;
  exhaustAllowed: boolean;
  databaseName: string;
  command: Document;
  options: OpQueryOptions;

  constructor(databaseName: string, command: Document, options: OpQueryOptions) {
    // Basic options needed to be passed in
    if (command == null)
      throw new MongoInvalidArgumentError('Query document must be specified for query');

    // Basic optionsa
    this.databaseName = databaseName;
    this.command = command;
    this.command.$db = databaseName;

    // Ensure empty options
    this.options = options ?? {};

    // Additional options
    this.requestId = options.requestId ? options.requestId : OpMsgRequest.getRequestId();

    // Serialization option
    this.serializeFunctions =
      typeof options.serializeFunctions === 'boolean' ? options.serializeFunctions : false;
    this.ignoreUndefined =
      typeof options.ignoreUndefined === 'boolean' ? options.ignoreUndefined : false;
    this.checkKeys = typeof options.checkKeys === 'boolean' ? options.checkKeys : false;

View on GitHub (pinned to dce7939f86)