What causes "Tailable cursor does not support limit" in mongodb/node-mongodb-native?

Remove .limit() on tailable cursors; track count yourself and close() when done

mongodb/node-mongodb-native · error · MongoTailableCursorError

Tailable cursor does not support limit

Error message

Tailable cursor does not support limit

What it means

Thrown as MongoTailableCursorError by FindCursor.limit() when findOptions.tailable is true. Tailable cursors are open-ended streams over a capped collection; a limit would close the cursor after N docs, breaking the tailing contract, so the driver forbids it client-side.

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 3366c21a63)

Solutions

Remove .limit() on tailable cursors; track count yourself and close() when done
If you need a bounded read, query the capped collection without tailable and apply limit
Read N documents in your for-await loop then break and close()

Example fix

// before
coll.find({}, { tailable: true }).limit(10);
// after
const c = coll.find({}, { tailable: true });
let i = 0;
for await (const doc of c) { if (++i >= 10) break; }
await c.close();

Defensive patterns

Strategy: validation

Validate before calling

function limitSafe(cursor, n) {
  if (cursor.findOptions?.tailable) {
    throw new Error('cannot limit a tailable cursor; count manually and close()');
  }
  return cursor.limit(n);
}

Prevention

Never call .limit() on tailable cursors
Track count yourself and break/close when reached
Use a non-tailable query for bounded reads

When it happens

Trigger: coll.find({}, { tailable: true }).limit(100) or coll.find({}, { tailable: true, awaitData: true }).limit(N).

Common situations: Trying to 'batch' tailing reads with a limit; reusing a find-options preset that includes limit on a tailable query.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/dab3da28dafe6878.json. Report an issue: GitHub.