mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Option "allowDiskUse" requires a sort specification

Error message

Option "allowDiskUse" requires a sort specification

What it means

Thrown by FindCursor.allowDiskUse() (MongoInvalidArgumentError) when no sort specification has been set on the cursor. allowDiskUse only matters for blocking sort operations that may exceed the 100MB memory limit; without a sort it has no effect, so the driver requires .sort() to be called first.

Source

Thrown at src/cursor/find_cursor.ts:436

    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');
    }

    // As of 6.0 the default is true. This allows users to get back to the old behavior.
    if (!allow) {
      this.findOptions.allowDiskUse = false;
      return this;
    }

    this.findOptions.allowDiskUse = true;
    return this;
  }

  /**
   * 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 {

View on GitHub (pinned to 3366c21a63)

Solutions

1. Call .sort(...) before .allowDiskUse()
2. Remove the allowDiskUse() call if you are not sorting
3. On MongoDB >= 6.0 allowDiskUse defaults to true for finds that need it; the explicit call is usually unnecessary

Example fix

// before
coll.find({ bigQuery }).allowDiskUse();
// after
coll.find({ bigQuery }).sort({ field: 1 }).allowDiskUse();

function allowDiskUseSafe(cursor, allow = true) {
  if (!cursor.findOptions?.sort) {
    throw new Error('allowDiskUse requires a prior .sort() call');
  }
  return cursor.allowDiskUse(allow);
}

When it happens

Trigger: coll.find({}).allowDiskUse() without a preceding .sort(...).

Common situations: Copy-pasting allowDiskUse into find chains that don't sort; enabling it defensively as a 'performance flag'.

Related errors

• ${name} is not a valid query modifier
• Invalid query modifier: ${name}
• Argument for maxAwaitTimeMS must be a number
• Argument for maxTimeMS must be a number
• Tailable cursor does not support sorting

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