mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Flag ${flag} must be a boolean value

Error message

Flag ${flag} must be a boolean value

What it means

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.

Source

Thrown at src/cursor/abstract_cursor.ts:685

        }
      }
    }
    return array;
  }
  /**
   * Add a cursor flag to the cursor
   *
   * @param flag - The flag to set, must be one of following ['tailable', 'oplogReplay', 'noCursorTimeout', 'awaitData', 'partial' -.
   * @param value - The flag boolean value.
   */
  addCursorFlag(flag: CursorFlag, value: boolean): this {
    this.throwIfInitialized();
    if (!CURSOR_FLAGS.includes(flag)) {
      throw new MongoInvalidArgumentError(`Flag ${flag} is not one of ${CURSOR_FLAGS}`);
    }

    if (typeof value !== 'boolean') {
      throw new MongoInvalidArgumentError(`Flag ${flag} must be a boolean value`);
    }

    this.cursorOptions[flag] = value;
    return this;
  }

  /**
   * Map all documents using the provided function
   * If there is a transform set on the cursor, that will be called first and the result passed to
   * this function's transform.
   *
   * @remarks
   *
   * **Note** Cursors use `null` internally to indicate that there are no more documents in the cursor. Providing a mapping
   * function that maps values to `null` will result in the cursor closing itself before it has finished iterating
   * all documents.  This will **not** result in a memory leak, just surprising behavior.  For example:
   *
   * ```typescript

View on GitHub (pinned to 3366c21a63)

Solutions

1. Coerce explicitly: addCursorFlag('tailable', Boolean(configValue)).
2. When reading env vars: addCursorFlag('tailable', process.env.TAILABLE === 'true').
3. Pass a literal true/false.

Example fix

// before
cursor.addCursorFlag('tailable', config.tailable); // config.tailable is '1'
// after
cursor.addCursorFlag('tailable', config.tailable === true || config.tailable === 'true');

if (typeof value !== 'boolean') value = Boolean(value);

function isBoolean(v): v is boolean { return typeof v === 'boolean'; }

When it happens

Trigger: Calling addCursorFlag('tailable', 1), addCursorFlag('tailable', 'true'), addCursorFlag('tailable', 'yes'), or passing undefined explicitly. Truthy non-booleans are not coerced.

Common situations: Loading flag values from env vars or config files where they arrive as strings; arithmetic or bitfield-derived values; assuming JS truthiness is accepted.

Related errors

• Invalid read preference: ${readPreference}
• Argument for maxTimeMS must be a number
• Operation "batchSize" requires an integer
• Cursor options must be an object
• User input for option 'mongodbLogComponentSeverities' object

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/aae0569b8d950001.json. Report an issue: GitHub.