{"record":{"id":"aae0569b8d950001","repo":"mongodb/node-mongodb-native","slug":"flag-flag-must-be-a-boolean-value","errorCode":null,"errorMessage":"Flag ${flag} must be a boolean value","messagePattern":"Flag (.+?) must be a boolean value","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/cursor/abstract_cursor.ts","lineNumber":685,"sourceCode":"        }\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\n   * function that maps values to `null` will result in the cursor closing itself before it has finished iterating\n   * all documents.  This will **not** result in a memory leak, just surprising behavior.  For example:\n   *\n   * ```typescript","sourceCodeStart":667,"sourceCodeEnd":703,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cursor/abstract_cursor.ts#L667-L703","documentation":"Thrown as a MongoInvalidArgumentError from addCursorFlag() when the value argument fails `typeof value !== 'boolean'`. Cursor flags are single bits on the wire, so a non-boolean value cannot be encoded; passing a truthy/falsy non-boolean (1, 0, 'true', undefined) would be a silent footgun, hence the strict type check. It is the second guard in addCursorFlag, run after the flag-name check.","triggerScenarios":"cursor.addCursorFlag('tailable', 1); cursor.addCursorFlag('awaitData', 'true'); cursor.addCursorFlag('noCursorTimeout', undefined) where the value was meant to be toggled.","commonSituations":"Passing a config value typed as any/number from JSON; toggling flags with a bitmask integer instead of a boolean; spreading an options object whose flag values are strings.","solutions":["Pass an explicit boolean: cursor.addCursorFlag('tailable', true).","Coerce intentionally if you must: cursor.addCursorFlag('tailable', Boolean(value)).","Type the caller so flag values are boolean at the source."],"exampleFix":"// before: number/string instead of boolean\ncursor.addCursorFlag('tailable', 1);\n\n// after: explicit boolean\ncursor.addCursorFlag('tailable', true);","handlingStrategy":"type-guard","validationCode":"if (typeof value !== 'boolean') {\n  throw new TypeError(`Cursor flag ${flag} requires a boolean`);\n}\ncursor.addCursorFlag(flag, value);","typeGuard":"function isBoolean(v: unknown): v is boolean {\n  return typeof v === 'boolean';\n}","tryCatchPattern":null,"preventionTips":["Always pass literal true/false to addCursorFlag().","Coerce explicitly with Boolean(...) if the source value is loosely typed.","Avoid passing 0/1 or 'true'/'false' strings from config."],"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"}