mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Invalid query modifier

Error message

Invalid query modifier: ${name}

What it means

Thrown by FindCursor.addQueryModifier when the name does begin with '$' but is not one of the supported modifiers. Supported fields (after stripping '$') are: comment, explain, hint, max, maxTimeMS, min, orderby, query, returnKey, showDiskLoc. Any other modifier name falls through the switch to this default error.

Solutions

1. Use the typed equivalent (e.g. cursor.comment() instead of $comment, cursor.hint() instead of $hint).
2. Drop the unsupported modifier if the server version no longer honors it.
3. Embed the value directly in the filter or command document instead of via addQueryModifier.

Example fix

// before
cursor.addQueryModifier('$maxScan', 1000);

// after
// $maxScan is unsupported; remove it or use a $limit stage in aggregation instead

const SUPPORTED = new Set(['$comment','$explain','$hint','$max','$maxTimeMS','$min','$orderby','$query','$returnKey','$showDiskLoc']);
function addKnownModifier(cursor, name, value) {
  if (!SUPPORTED.has(name)) throw new Error(`Unsupported query modifier: ${name}`);
  return cursor.addQueryModifier(name, value);
}

function isSupportedModifier(name) {
  return ['$comment','$explain','$hint','$max','$maxTimeMS','$min','$orderby','$query','$returnKey','$showDiskLoc'].includes(name);
}

When it happens

Trigger: cursor.addQueryModifier('$snapshot', true); cursor.addQueryModifier('$maxScan', 1000); cursor.addQueryModifier('$someLegacyField', value); passing a modifier that the modern wire protocol no longer supports.

Common situations: Migrating from the 2.x driver that tolerated arbitrary $-prefixed modifiers; using modifiers removed in newer MongoDB server versions; copy-pasting deprecated wire-protocol options like $maxScan or $snapshot.

Related errors

• Invalid first parameter to count
• is not a valid query modifier
• Option "allowDiskUse" requires a sort specification
• timeoutMS cannot be used with explain when explain is…
• Argument for maxAwaitTimeMS must be a number

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

Appendix: source

Thrown at src/cursor/find_cursor.ts:317

      case 'orderby':
        this.findOptions.sort = formatSort(value as string | Document);
        break;

      case 'query':
        this.cursorFilter = value as Document;
        break;

      case 'returnKey':
        this.findOptions.returnKey = value as boolean;
        break;

      case 'showDiskLoc':
        this.findOptions.showRecordId = value as boolean;
        break;

      default:
        throw new MongoInvalidArgumentError(`Invalid query modifier: ${name}`);
    }

    return this;
  }

  /**
   * Add a comment to the cursor query allowing for tracking the comment in the log.
   *
   * @param value - The comment attached to this query.
   */
  comment(value: string): this {
    this.throwIfInitialized();
    this.findOptions.comment = value;
    return this;
  }

  /**
   * Set a maxAwaitTimeMS on a tailing cursor query to allow to customize the timeout value for the option awaitData (Only supported on MongoDB 3.2 or higher, ignored otherwise)

View on GitHub (pinned to dce7939f86)