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 when no sort specification has been set. allowDiskUse is only meaningful for blocking sort operations that would otherwise exceed the 100MB memory limit; without a sort there is nothing for the disk spill to serve, so the driver rejects the call as a MongoInvalidArgumentError.

Solutions

1. Call cursor.sort(...) before cursor.allowDiskUse().
2. Remove allowDiskUse if the query does not sort; it has no effect.
3. Pass allowDiskUse only inside the same code path that sets sort.

Example fix

// before
collection.find({ bigFilter: true }).allowDiskUse();

// after
collection.find({ bigFilter: true }).sort({ ts: 1 }).allowDiskUse();

function safeAllowDiskUse(cursor, sortSpec) {
  if (sortSpec == null) throw new Error('allowDiskUse requires a prior sort specification');
  cursor.sort(sortSpec);
  return cursor.allowDiskUse();
}

function hasSortSpec(findOptions) { return findOptions?.sort != null; }

When it happens

Trigger: collection.find({}).allowDiskUse(); calling .allowDiskUse() before .sort(); constructing options where sort is conditionally set and the condition evaluated false.

Common situations: Adding allowDiskUse defensively to large-result queries; copy-pasting from a sorted query; setting allowDiskUse in a builder that does not guarantee a sort.

Related errors

• Invalid first parameter to count
• Invalid query modifier
• is not a valid query modifier
• Tailable cursor does not support sorting
• timeoutMS cannot be used with explain when explain is…

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

Appendix: 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 dce7939f86)