mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Invalid query modifier: ${name}

Error message

Invalid query modifier: ${name}

What it means

Thrown by FindCursor.addQueryModifier() (MongoInvalidArgumentError) in the default switch case when the name is '$'-prefixed but not one of the recognized modifiers: comment, explain, hint, max, maxTimeMS, min, orderby, query, returnKey, showDiskLoc. Any other $name falls through to the default and is rejected.

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

Solutions

1. Use the exact supported modifier name ($comment, $explain, $hint, $max, $maxTimeMS, $min, $orderby, $query, $returnKey, $showDiskLoc)
2. Use the dedicated builder method where one exists (.comment, .hint, .max, .min, .maxTimeMS, .sort, .returnKey, .showRecordId)
3. Pass unsupported options directly in find() options rather than via addQueryModifier

Example fix

// before
cursor.addQueryModifier('$maxtimems', 1000); // typo
// after
cursor.maxTimeMS(1000);

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

const isSupportedModifier = (s) =>
  ['$comment','$explain','$hint','$max','$maxTimeMS','$min','$orderby','$query','$returnKey','$showDiskLoc'].includes(s);

When it happens

Trigger: cursor.addQueryModifier('$snapshot', true), '$maxScan', '$showDiskLoc' is allowed but a typo like '$maxtimmes' or '$maxTimeMSs' hits default. Also genuinely-unsupported modifiers.

Common situations: Typos in modifier names, using modifiers removed in modern server versions, or passing a server-internal $ field that the driver does not whitelist.

Related errors

• ${name} is not a valid query modifier
• Argument for maxAwaitTimeMS must be a number
• Argument for maxTimeMS must be a number
• Option "allowDiskUse" requires a sort specification
• Operation "limit" requires an integer

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