mongodb/node-mongodb-native · error · MongoAPIError

maxTimeMS must be configured on the command document directl

Error message

maxTimeMS must be configured on the command document directly, to configure getMore.maxTimeMS use cursor.setMaxTimeMS()

What it means

For RunCommandCursor the server-side maxTimeMS of the initial command must be embedded in the command document; the fluent maxTimeMS() builder is disabled. To control getMore.maxTimeMS (the per-batch wait on tailable-await cursors), use cursor.setMaxTimeMS(). For an overall deadline, use the timeoutMS option.

Source

Thrown at src/cursor/run_command_cursor.ts:122

  /** Unsupported for RunCommandCursor: readConcern must be configured directly on command document */
  public override withReadConcern(_: ReadConcernLike): never {
    throw new MongoAPIError(
      'RunCommandCursor does not support readConcern it must be attached to the command being run'
    );
  }

  /** Unsupported for RunCommandCursor: various cursor flags must be configured directly on command document */
  public override addCursorFlag(_: string, __: boolean): never {
    throw new MongoAPIError(
      'RunCommandCursor does not support cursor flags, they must be attached to the command being run'
    );
  }

  /**
   * Unsupported for RunCommandCursor: maxTimeMS must be configured directly on command document
   */
  public override maxTimeMS(_: number): never {
    throw new MongoAPIError(
      'maxTimeMS must be configured on the command document directly, to configure getMore.maxTimeMS use cursor.setMaxTimeMS()'
    );
  }

  /** Unsupported for RunCommandCursor: batchSize must be configured directly on command document */
  public override batchSize(_: number): never {
    throw new MongoAPIError(
      'batchSize must be configured on the command document directly, to configure getMore.batchSize use cursor.setBatchSize()'
    );
  }

  /** @internal */
  private db: Db;

  /** @internal */
  constructor(db: Db, command: Document, options: RunCursorCommandOptions = {}) {
    super(db.client, ns(db.namespace), options);
    this.db = db;

View on GitHub (pinned to 3366c21a63)

Solutions

1. Add maxTimeMS to the command document: db.runCursorCommand({ ...cmd, maxTimeMS: 1000 })
2. For getMore maxTimeMS on a tailable-await cursor, call cursor.setMaxTimeMS(n)
3. Use timeoutMS in the options for a CSOT-style whole-operation deadline

Example fix

// before
db.runCursorCommand(cmd).maxTimeMS(1000);
// after
db.runCursorCommand({ ...cmd, maxTimeMS: 1000 });

if (cursor instanceof RunCommandCursor) {
  throw new Error('Put maxTimeMS on the command document; use cursor.setMaxTimeMS() for getMore');
}

function isRunCommandCursor(c: AbstractCursor): c is RunCommandCursor {
  return c instanceof RunCommandCursor;
}

When it happens

Trigger: Calling .maxTimeMS(1000) on a RunCommandCursor returned by db.runCursorCommand().

Common situations: Migrating find()-based code that applied maxTimeMS uniformly; mixing legacy maxTimeMS patterns with runCursorCommand.

Related errors

• Clone not supported, create a new cursor with db.runCursorCo
• RunCommandCursor does not support readConcern it must be att
• RunCommandCursor does not support cursor flags, they must be
• batchSize must be configured on the command document directl
• Cannot specify maxAwaitTimeMS >= timeoutMS for a tailable aw

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