{"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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cursor/abstract_cursor.ts#L667-L703","documentation":"Thrown by cursor.addCursorFlag(flag, value) when value is not a boolean. Cursor flags are binary toggles on the wire protocol; the driver rejects numbers, strings, or undefined to avoid silent coercion bugs.","triggerScenarios":"Calling addCursorFlag('tailable', 1), addCursorFlag('tailable', 'true'), addCursorFlag('tailable', 'yes'), or passing undefined explicitly. Truthy non-booleans are not coerced.","commonSituations":"Loading flag values from env vars or config files where they arrive as strings; arithmetic or bitfield-derived values; assuming JS truthiness is accepted.","solutions":["Coerce explicitly: addCursorFlag('tailable', Boolean(configValue)).","When reading env vars: addCursorFlag('tailable', process.env.TAILABLE === 'true').","Pass a literal true/false."],"exampleFix":"// before\ncursor.addCursorFlag('tailable', config.tailable); // config.tailable is '1'\n// after\ncursor.addCursorFlag('tailable', config.tailable === true || config.tailable === 'true');","handlingStrategy":"validation","validationCode":"if (typeof value !== 'boolean') value = Boolean(value);","typeGuard":"function isBoolean(v): v is boolean { return typeof v === 'boolean'; }","tryCatchPattern":null,"preventionTips":["Coerce env-var/config values with Boolean() before passing.","Type config schemas so cursor flags are typed as boolean.","Avoid passing truthy non-booleans that rely on implicit coercion."],"tags":["cursor","options","type-validation"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}