mongodb/node-mongodb-native · error · MongoAPIError

maxTimeMS must be configured on the command document…

Error message

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

What it means

Thrown by RunCommandCursor.maxTimeMS because the inherited maxTimeMS method would set the deadline on the initial command, but the command document is frozen and sent verbatim by runCursorCommand. The driver distinguishes the initial-command maxTimeMS (must live on the command document) from getMore.maxTimeMS (set via cursor.setMaxTimeMS). This override routes users to the correct location.

Solutions

  1. For the initial command deadline: put maxTimeMS on the command document, db.runCursorCommand({ find: 'coll', filter: {}, maxTimeMS: 1000 }).
  2. For getMore.maxTimeMS (tailable await): call cursor.setMaxTimeMS(1000) which sets getMoreOptions.maxAwaitTimeMS.
  3. Use the timeoutMS option on RunCursorCommandOptions for client-side operation timeouts.

Example fix

// before
cursor.maxTimeMS(1000);

// after
db.runCursorCommand({ find: 'coll', filter: {}, maxTimeMS: 1000 });
// or for getMore:
cursor.setMaxTimeMS(1000);
Defensive patterns

Strategy: validation

Validate before calling

function applyMaxTimeMS(db, cursor, cmd, ms, scope) {
  if (scope === 'getMore') return cursor.setMaxTimeMS(ms);
  // initial command deadline: rebuild the command
  return db.runCursorCommand({ ...cmd, maxTimeMS: ms });
}

Type guard

function isRunCommandCursor(cursor) { return cursor instanceof RunCommandCursor; }

Prevention

When it happens

Trigger: Calling cursor.maxTimeMS(1000) on a RunCommandCursor; generic cursor configuration that always calls maxTimeMS; setting a server-side deadline on a runCursorCommand query.

Common situations: Reusing find/aggregate timeout setup code verbatim; building a generic cursor builder that calls maxTimeMS for every cursor type.

Related errors

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

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