{"id":"97f324efd95b0208","repo":"mongodb/node-mongodb-native","slug":"invalid-query-modifier-name","errorCode":null,"errorMessage":"Invalid query modifier: ${name}","messagePattern":"Invalid query modifier: (.+?)","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/cursor/find_cursor.ts","lineNumber":317,"sourceCode":"\n      case 'orderby':\n        this.findOptions.sort = formatSort(value as string | Document);\n        break;\n\n      case 'query':\n        this.cursorFilter = value as Document;\n        break;\n\n      case 'returnKey':\n        this.findOptions.returnKey = value as boolean;\n        break;\n\n      case 'showDiskLoc':\n        this.findOptions.showRecordId = value as boolean;\n        break;\n\n      default:\n        throw new MongoInvalidArgumentError(`Invalid query modifier: ${name}`);\n    }\n\n    return this;\n  }\n\n  /**\n   * Add a comment to the cursor query allowing for tracking the comment in the log.\n   *\n   * @param value - The comment attached to this query.\n   */\n  comment(value: string): this {\n    this.throwIfInitialized();\n    this.findOptions.comment = value;\n    return this;\n  }\n\n  /**\n   * 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)","sourceCodeStart":299,"sourceCodeEnd":335,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cursor/find_cursor.ts#L299-L335","documentation":"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.","triggerScenarios":"cursor.addQueryModifier('$snapshot', true), '$maxScan', '$showDiskLoc' is allowed but a typo like '$maxtimmes' or '$maxTimeMSs' hits default. Also genuinely-unsupported modifiers.","commonSituations":"Typos in modifier names, using modifiers removed in modern server versions, or passing a server-internal $ field that the driver does not whitelist.","solutions":["Use the exact supported modifier name ($comment, $explain, $hint, $max, $maxTimeMS, $min, $orderby, $query, $returnKey, $showDiskLoc)","Use the dedicated builder method where one exists (.comment, .hint, .max, .min, .maxTimeMS, .sort, .returnKey, .showRecordId)","Pass unsupported options directly in find() options rather than via addQueryModifier"],"exampleFix":"// before\ncursor.addQueryModifier('$maxtimems', 1000); // typo\n// after\ncursor.maxTimeMS(1000);","handlingStrategy":"validation","validationCode":"const ALLOWED = new Set(['$comment','$explain','$hint','$max','$maxTimeMS','$min','$orderby','$query','$returnKey','$showDiskLoc']);\nfunction addQueryModifierSafe(cursor, name, value) {\n  if (!ALLOWED.has(name)) throw new Error(`unsupported query modifier: ${name}`);\n  return cursor.addQueryModifier(name, value);\n}","typeGuard":"const isSupportedModifier = (s) =>\n  ['$comment','$explain','$hint','$max','$maxTimeMS','$min','$orderby','$query','$returnKey','$showDiskLoc'].includes(s);","tryCatchPattern":null,"preventionTips":["Use only the whitelisted modifier names","Prefer the dedicated builder methods (.maxTimeMS, .hint, .sort, etc.)","Pass unsupported options directly in find() options"],"tags":["find","query-modifier","validation"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}