{"record":{"id":"382848471a76f5f6","repo":"mongodb/node-mongodb-native","slug":"flag-flag-is-not-one-of-cursor-flags","errorCode":null,"errorMessage":"Flag ${flag} is not one of ${CURSOR_FLAGS}","messagePattern":"Flag (.+?) is not one of (.+?)","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/cursor/abstract_cursor.ts","lineNumber":681,"sourceCode":"        // Note: previous versions of this logic used `array.push(...)`, which adds each item\n        // to the callstack.  For large arrays, this can exceed the maximum call size.\n        for (const doc of docs) {\n          array.push(doc);\n        }\n      }\n    }\n    return array;\n  }\n  /**\n   * Add a cursor flag to the cursor\n   *\n   * @param flag - The flag to set, must be one of following ['tailable', 'oplogReplay', 'noCursorTimeout', 'awaitData', 'partial' -.\n   * @param value - The flag boolean value.\n   */\n  addCursorFlag(flag: CursorFlag, value: boolean): this {\n    this.throwIfInitialized();\n    if (!CURSOR_FLAGS.includes(flag)) {\n      throw new MongoInvalidArgumentError(`Flag ${flag} is not one of ${CURSOR_FLAGS}`);\n    }\n\n    if (typeof value !== 'boolean') {\n      throw new MongoInvalidArgumentError(`Flag ${flag} must be a boolean value`);\n    }\n\n    this.cursorOptions[flag] = value;\n    return this;\n  }\n\n  /**\n   * Map all documents using the provided function\n   * If there is a transform set on the cursor, that will be called first and the result passed to\n   * this function's transform.\n   *\n   * @remarks\n   *\n   * **Note** Cursors use `null` internally to indicate that there are no more documents in the cursor. Providing a mapping","sourceCodeStart":663,"sourceCodeEnd":699,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cursor/abstract_cursor.ts#L663-L699","documentation":"Thrown as a MongoInvalidArgumentError from addCursorFlag() when the flag argument is not in the CURSOR_FLAGS array (['tailable','oplogReplay','noCursorTimeout','awaitData','exhaust','partial']). The wire protocol only carries those six flag bits, so any other name has no effect and would silently be ignored; the driver rejects it to surface typos. The check runs after throwIfInitialized(), so it also cannot be applied once the cursor has begun iterating.","triggerScenarios":"cursor.addCursorFlag('await', true) (typo for awaitData); cursor.addCursorFlag('timeout', true) (not a wire flag); cursor.addCursorFlag('partialResults', true) (correct name is 'partial').","commonSituations":"Guessing flag names from MongoDB docs prose instead of the driver's CURSOR_FLAGS list; copying a flag name from a different driver's API.","solutions":["Use one of the exact CURSOR_FLAGS names: 'tailable', 'oplogReplay', 'noCursorTimeout', 'awaitData', 'exhaust', 'partial'.","For options that are not wire flags (timeout, comment, batchSize), use the corresponding cursor method or the options object instead.","Add a TypeScript annotation so the compiler rejects invalid flag names: addCursorFlag(flag: CursorFlag, value: boolean)."],"exampleFix":"// before: typo, not a real wire flag\ncursor.addCursorFlag('await', true);\n\n// after: use the exact flag name\ncursor.addCursorFlag('awaitData', true);","handlingStrategy":"type-guard","validationCode":"const VALID_FLAGS = ['tailable','oplogReplay','noCursorTimeout','awaitData','exhaust','partial'] as const;\nif (!VALID_FLAGS.includes(flag as any)) {\n  throw new RangeError(`Invalid cursor flag: ${flag}`);\n}","typeGuard":"import { CURSOR_FLAGS, type CursorFlag } from 'mongodb';\nfunction isCursorFlag(v: unknown): v is CursorFlag {\n  return typeof v === 'string' && (CURSOR_FLAGS as readonly string[]).includes(v);\n}","tryCatchPattern":null,"preventionTips":["Import CURSOR_FLAGS from the driver and validate against it.","Type flag arguments as CursorFlag so the compiler rejects typos.","Remember the six valid names; 'partial' not 'partialResults', 'awaitData' not 'await'."],"tags":["cursor","cursor-flags","invalid-argument","typescript"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}