{"record":{"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/dce7939f86fb283e167ad709955abedb7bf23124/src/cursor/run_command_cursor.ts#L104-L140","documentation":"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.","triggerScenarios":"Calling cursor.maxTimeMS(1000) on a RunCommandCursor; generic cursor configuration that always calls maxTimeMS; setting a server-side deadline on a runCursorCommand query.","commonSituations":"Reusing find/aggregate timeout setup code verbatim; building a generic cursor builder that calls maxTimeMS for every cursor type.","solutions":["For the initial command deadline: put maxTimeMS on the command document, db.runCursorCommand({ find: 'coll', filter: {}, maxTimeMS: 1000 }).","For getMore.maxTimeMS (tailable await): call cursor.setMaxTimeMS(1000) which sets getMoreOptions.maxAwaitTimeMS.","Use the timeoutMS option on RunCursorCommandOptions for client-side operation timeouts."],"exampleFix":"// before\ncursor.maxTimeMS(1000);\n\n// after\ndb.runCursorCommand({ find: 'coll', filter: {}, maxTimeMS: 1000 });\n// or for getMore:\ncursor.setMaxTimeMS(1000);","handlingStrategy":"validation","validationCode":"function applyMaxTimeMS(db, cursor, cmd, ms, scope) {\n  if (scope === 'getMore') return cursor.setMaxTimeMS(ms);\n  // initial command deadline: rebuild the command\n  return db.runCursorCommand({ ...cmd, maxTimeMS: ms });\n}","typeGuard":"function isRunCommandCursor(cursor) { return cursor instanceof RunCommandCursor; }","tryCatchPattern":null,"preventionTips":["Distinguish initial-command maxTimeMS (on the command) from getMore.maxTimeMS (via setMaxTimeMS).","Consider using RunCursorCommandOptions.timeoutMS for client-side deadlines."],"tags":["run-command-cursor","timeout","maxtimems","unsupported"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}