mongodb/node-mongodb-native · error · MongoTailableCursorError

Tailable cursor does not support sorting

Error message

Tailable cursor does not support sorting

What it means

Thrown by FindCursor.sort when findOptions.tailable is true. Tailable cursors follow the natural order of documents in a capped collection as written by the server; applying a client-side sort is incompatible with that because it would require materializing and reordering the live stream. Subclass MongoTailableCursorError (extends MongoAPIError).

Solutions

1. Remove the .sort() call on a tailable cursor; rely on insertion order.
2. If ordering is required, use a non-tailable query against the capped collection instead.
3. Switch to a Change Stream for ordered event processing rather than a tailable cursor.

Example fix

// before
collection.find({}, { tailable: true }).sort({ ts: -1 });

// after
collection.find({}, { tailable: true }); // natural order

function safeSort(cursor, sort, opts) {
  if (opts?.tailable) throw new Error('Cannot sort a tailable cursor');
  return cursor.sort(sort);
}

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

When it happens

Trigger: collection.find({}, { tailable: true }).sort({ ts: -1 }); setting tailable via addCursorFlag('tailable', true) then calling .sort(); following the oplog with a sort applied.

Common situations: Building a change listener over a capped collection and mistakenly trying to order events; reusing a find-options builder that always sets sort; converting a normal query to tailable without removing sort.

Related errors

• Tailable cursor does not support limit
• Tailable cursor does not support skip
• Argument for maxAwaitTimeMS must be a number
• Option "allowDiskUse" requires a sort specification
• Argument for maxTimeMS must be a number

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

Appendix: source

Thrown at src/cursor/find_cursor.ts:419

   * }});
   * ```
   */
  project<T extends Document = Document>(value: Document): FindCursor<T> {
    this.throwIfInitialized();
    this.findOptions.projection = value;
    return this as unknown as FindCursor<T>;
  }

  /**
   * Sets the sort order of the cursor query.
   *
   * @param sort - The key or keys set for the sort.
   * @param direction - The direction of the sorting (1 or -1).
   */
  sort(sort: Sort | string, direction?: SortDirection): this {
    this.throwIfInitialized();
    if (this.findOptions.tailable) {
      throw new MongoTailableCursorError('Tailable cursor does not support sorting');
    }

    this.findOptions.sort = formatSort(sort, direction);
    return this;
  }

  /**
   * Allows disk use for blocking sort operations exceeding 100MB memory. (MongoDB 3.2 or higher)
   *
   * @remarks
   * {@link https://www.mongodb.com/docs/manual/reference/command/find/#find-cmd-allowdiskuse | find command allowDiskUse documentation}
   */
  allowDiskUse(allow = true): this {
    this.throwIfInitialized();

    if (!this.findOptions.sort) {
      throw new MongoInvalidArgumentError('Option "allowDiskUse" requires a sort specification');
    }

View on GitHub (pinned to dce7939f86)