{"record":{"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/dce7939f86fb283e167ad709955abedb7bf23124/src/cursor/find_cursor.ts#L299-L335","documentation":"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.","triggerScenarios":"cursor.addQueryModifier('$snapshot', true); cursor.addQueryModifier('$maxScan', 1000); cursor.addQueryModifier('$someLegacyField', value); passing a modifier that the modern wire protocol no longer supports.","commonSituations":"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.","solutions":["Use the typed equivalent (e.g. cursor.comment() instead of $comment, cursor.hint() instead of $hint).","Drop the unsupported modifier if the server version no longer honors it.","Embed the value directly in the filter or command document instead of via addQueryModifier."],"exampleFix":"// before\ncursor.addQueryModifier('$maxScan', 1000);\n\n// after\n// $maxScan is unsupported; remove it or use a $limit stage in aggregation instead","handlingStrategy":"validation","validationCode":"const SUPPORTED = new Set(['$comment','$explain','$hint','$max','$maxTimeMS','$min','$orderby','$query','$returnKey','$showDiskLoc']);\nfunction addKnownModifier(cursor, name, value) {\n  if (!SUPPORTED.has(name)) throw new Error(`Unsupported query modifier: ${name}`);\n  return cursor.addQueryModifier(name, value);\n}","typeGuard":"function isSupportedModifier(name) {\n  return ['$comment','$explain','$hint','$max','$maxTimeMS','$min','$orderby','$query','$returnKey','$showDiskLoc'].includes(name);\n}","tryCatchPattern":null,"preventionTips":["Keep a whitelist of supported modifiers in your codebase.","Drop legacy modifiers like $maxScan/$snapshot removed in modern server versions."],"tags":["find","query-modifier","options-validation","deprecated"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}