{"record":{"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/dce7939f86fb283e167ad709955abedb7bf23124/src/cursor/abstract_cursor.ts#L786-L822","documentation":"Thrown as a MongoTailableCursorError (a subclass of MongoAPIError) from batchSize() when cursorOptions.tailable is true. A tailable cursor follows the tail of a capped collection and must not pin itself to a fixed batch size, because doing so would interfere with the await/blocking semantics that let tailing work; the driver rejects batchSize on tailable cursors to prevent this. The guard runs before the integer check, and only when the cursor is not yet initialized.","triggerScenarios":"Building a cursor with addCursorFlag('tailable', true) (or { tailable: true }) and then calling cursor.batchSize(N); configuring a tailable change-stream-style cursor and trying to tune batch size.","commonSituations":"Reusing a generic cursor-builder helper that always sets batchSize, on a tailable cursor; enabling tailable after setting batchSize in a chained config.","solutions":["Remove the batchSize call/option for tailable cursors; rely on the server default batch sizing.","If you need backpressure control on a tailable cursor, manage it at the consumer side (e.g. stream highWaterMark) rather than via batchSize.","Split your cursor-builder so tailable and non-tailable paths do not share the batchSize configuration."],"exampleFix":"// before: batchSize on a tailable cursor\nconst cursor = collection.find(filter, { tailable: true, awaitData: true });\ncursor.batchSize(100); // throws MongoTailableCursorError\n\n// after: drop batchSize for tailable cursors\nconst cursor = collection.find(filter, { tailable: true, awaitData: true });","handlingStrategy":"validation","validationCode":"if (opts.tailable && opts.batchSize != null) {\n  throw new RangeError('batchSize is not supported on tailable cursors');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Do not set batchSize on tailable cursors.","Split cursor-builder helpers into tailable and non-tailable variants.","Control backpressure at the consumer/stream level for tailable cursors."],"tags":["cursor","tailable","batch-size","invalid-argument"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}