{"id":"62767a4690e0d0ba","repo":"mongodb/node-mongodb-native","slug":"tailable-cursor-does-not-support-batchsize","errorCode":null,"errorMessage":"Tailable cursor does not support batchSize","messagePattern":"Tailable cursor does not support batchSize","errorType":"exception","errorClass":"MongoTailableCursorError","httpStatus":null,"severity":"error","filePath":"src/cursor/abstract_cursor.ts","lineNumber":804,"sourceCode":"  maxTimeMS(value: number): this {\n    this.throwIfInitialized();\n    if (typeof value !== 'number') {\n      throw new MongoInvalidArgumentError('Argument for maxTimeMS must be a number');\n    }\n\n    this.cursorOptions.maxTimeMS = value;\n    return this;\n  }\n\n  /**\n   * Set the batch size for the cursor.\n   *\n   * @param value - The number of documents to return per batch. See {@link https://www.mongodb.com/docs/manual/reference/command/find/|find command documentation}.\n   */\n  batchSize(value: number): this {\n    this.throwIfInitialized();\n    if (this.cursorOptions.tailable) {\n      throw new MongoTailableCursorError('Tailable cursor does not support batchSize');\n    }\n\n    if (typeof value !== 'number') {\n      throw new MongoInvalidArgumentError('Operation \"batchSize\" requires an integer');\n    }\n\n    this.cursorOptions.batchSize = value;\n    return this;\n  }\n\n  /**\n   * Rewind this cursor to its uninitialized state. Any options that are present on the cursor will\n   * remain in effect. Iterating this cursor will cause new queries to be sent to the server, even\n   * if the resultant data has already been retrieved by this cursor.\n   */\n  rewind(): void {\n    if (this.timeoutContext && this.timeoutContext.owner !== this) {\n      throw new MongoAPIError(`Cannot rewind cursor that does not own its timeout context.`);","sourceCodeStart":786,"sourceCodeEnd":822,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cursor/abstract_cursor.ts#L786-L822","documentation":"MongoTailableCursorError thrown by cursor.batchSize(value) when the cursor is tailable. Tailable cursors stream documents from a capped collection and the server ignores batchSize for them; the driver enforces this to prevent surprising behavior. The check fires before the type check on value.","triggerScenarios":"Calling cursor.addCursorFlag('tailable', true) followed by cursor.batchSize(100), or constructing with { tailable: true } then calling batchSize(). Also affects awaitData tailable cursors (change-stream-like patterns on capped collections).","commonSituations":"Reusing a find-options builder that always sets batchSize across all queries; migrating a normal find to a tailable find without removing batchSize; assuming batchSize controls getMore cadence on a tailable cursor (use maxAwaitTimeMS instead).","solutions":["Remove the batchSize call/config when the cursor is tailable.","To control getMore cadence on a tailable awaitData cursor, use maxAwaitTimeMS instead.","Split your query builder so tailable queries omit batchSize."],"exampleFix":"// before\ncursor.addCursorFlag('tailable', true).addCursorFlag('awaitData', true).batchSize(100);\n// after\ncursor.addCursorFlag('tailable', true).addCursorFlag('awaitData', true).maxAwaitTimeMS(1000);","handlingStrategy":"validation","validationCode":"if (cursorOptions.tailable) throw new Error('do not set batchSize on tailable cursor');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never set batchSize on tailable cursors — use maxAwaitTimeMS for cadence.","Branch your query builder so tailable queries omit batchSize.","Document which find queries are tailable so reviewers catch batchSize additions."],"tags":["cursor","tailable","options","misuse"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}