mongodb/node-mongodb-native · error · MongoTailableCursorError

Tailable cursor does not support limit

Error message

Tailable cursor does not support limit

What it means

Thrown by FindCursor.limit when findOptions.tailable is true. Tailable cursors follow an open-ended live stream from a capped collection and there is no well-defined point at which to stop on a document count; applying a limit would close the cursor prematurely and miss subsequent inserts. Subclass MongoTailableCursorError.

Solutions

1. Remove .limit() from the tailable cursor and bound consumption client-side (e.g. break out of the for-await loop after N docs).
2. If you need a bounded read, use a non-tailable query on the capped collection instead.
3. Use a Change Stream with a bounded consumer instead.

Example fix

// before
collection.find({}, { tailable: true }).limit(100);

// after
const cursor = collection.find({}, { tailable: true });
let count = 0;
for await (const doc of cursor) {
  if (++count > 100) break;
  handle(doc);
}

function safeLimit(cursor, value, opts) {
  if (opts?.tailable) throw new Error('Cannot limit a tailable cursor; bound consumption in the loop');
  return cursor.limit(value);
}

function isTailableCursor(opts) { return Boolean(opts?.tailable); }

When it happens

Trigger: collection.find({}, { tailable: true }).limit(100); setting tailable via options then calling .limit(); trying to read only the first N entries from an oplog tail.

Common situations: Reusing a find-query builder that always applies a default limit; converting a bounded query to a tailable stream without dropping limit.

Related errors

• Tailable cursor does not support skip
• Tailable cursor does not support sorting
• Argument for maxAwaitTimeMS must be a number
• Operation "limit" requires an integer
• Argument for maxTimeMS must be a number

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

Appendix: source

Thrown at src/cursor/find_cursor.ts:468

   * Set the collation options for the cursor.
   *
   * @param value - The cursor collation options (MongoDB 3.4 or higher) settings for update operation (see 3.4 documentation for available fields).
   */
  collation(value: CollationOptions): this {
    this.throwIfInitialized();
    this.findOptions.collation = value;
    return this;
  }

  /**
   * Set the limit for the cursor.
   *
   * @param value - The limit for the cursor query.
   */
  limit(value: number): this {
    this.throwIfInitialized();
    if (this.findOptions.tailable) {
      throw new MongoTailableCursorError('Tailable cursor does not support limit');
    }

    if (typeof value !== 'number') {
      throw new MongoInvalidArgumentError('Operation "limit" requires an integer');
    }

    this.findOptions.limit = value;
    return this;
  }

  /**
   * Set the skip for the cursor.
   *
   * @param value - The skip for the cursor query.
   */
  skip(value: number): this {
    this.throwIfInitialized();
    if (this.findOptions.tailable) {

View on GitHub (pinned to dce7939f86)