{"id":"1a35915cdb4c0f84","repo":"mongodb/node-mongodb-native","slug":"maxtimems-must-be-configured-on-the-command-docume","errorCode":null,"errorMessage":"maxTimeMS must be configured on the command document directly, to configure getMore.maxTimeMS use cursor.setMaxTimeMS()","messagePattern":"maxTimeMS must be configured on the command document directly, to configure getMore\\.maxTimeMS use cursor\\.setMaxTimeMS\\(\\)","errorType":"exception","errorClass":"MongoAPIError","httpStatus":null,"severity":"error","filePath":"src/cursor/run_command_cursor.ts","lineNumber":122,"sourceCode":"  /** Unsupported for RunCommandCursor: readConcern must be configured directly on command document */\n  public override withReadConcern(_: ReadConcernLike): never {\n    throw new MongoAPIError(\n      'RunCommandCursor does not support readConcern it must be attached to the command being run'\n    );\n  }\n\n  /** Unsupported for RunCommandCursor: various cursor flags must be configured directly on command document */\n  public override addCursorFlag(_: string, __: boolean): never {\n    throw new MongoAPIError(\n      'RunCommandCursor does not support cursor flags, they must be attached to the command being run'\n    );\n  }\n\n  /**\n   * Unsupported for RunCommandCursor: maxTimeMS must be configured directly on command document\n   */\n  public override maxTimeMS(_: number): never {\n    throw new MongoAPIError(\n      'maxTimeMS must be configured on the command document directly, to configure getMore.maxTimeMS use cursor.setMaxTimeMS()'\n    );\n  }\n\n  /** Unsupported for RunCommandCursor: batchSize must be configured directly on command document */\n  public override batchSize(_: number): never {\n    throw new MongoAPIError(\n      'batchSize must be configured on the command document directly, to configure getMore.batchSize use cursor.setBatchSize()'\n    );\n  }\n\n  /** @internal */\n  private db: Db;\n\n  /** @internal */\n  constructor(db: Db, command: Document, options: RunCursorCommandOptions = {}) {\n    super(db.client, ns(db.namespace), options);\n    this.db = db;","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cursor/run_command_cursor.ts#L104-L140","documentation":"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.","triggerScenarios":"Calling .maxTimeMS(1000) on a RunCommandCursor returned by db.runCursorCommand().","commonSituations":"Migrating find()-based code that applied maxTimeMS uniformly; mixing legacy maxTimeMS patterns with runCursorCommand.","solutions":["Add maxTimeMS to the command document: db.runCursorCommand({ ...cmd, maxTimeMS: 1000 })","For getMore maxTimeMS on a tailable-await cursor, call cursor.setMaxTimeMS(n)","Use timeoutMS in the options for a CSOT-style whole-operation deadline"],"exampleFix":"// before\ndb.runCursorCommand(cmd).maxTimeMS(1000);\n// after\ndb.runCursorCommand({ ...cmd, maxTimeMS: 1000 });","handlingStrategy":"type-guard","validationCode":"if (cursor instanceof RunCommandCursor) {\n  throw new Error('Put maxTimeMS on the command document; use cursor.setMaxTimeMS() for getMore');\n}","typeGuard":"function isRunCommandCursor(c: AbstractCursor): c is RunCommandCursor {\n  return c instanceof RunCommandCursor;\n}","tryCatchPattern":null,"preventionTips":["Embed maxTimeMS in the command document","Use cursor.setMaxTimeMS() only for tailable-await getMore","Prefer timeoutMS for whole-operation deadlines"],"tags":["cursor","timeout","runcommandcursor","api-misuse"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}