mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Flag must be a boolean value

Error message

Flag ${flag} must be a boolean value

What it means

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.

Solutions

1. Pass an explicit boolean: cursor.addCursorFlag('tailable', true).
2. Coerce intentionally if you must: cursor.addCursorFlag('tailable', Boolean(value)).
3. Type the caller so flag values are boolean at the source.

Example fix

// before: number/string instead of boolean
cursor.addCursorFlag('tailable', 1);

// after: explicit boolean
cursor.addCursorFlag('tailable', true);

if (typeof value !== 'boolean') {
  throw new TypeError(`Cursor flag ${flag} requires a boolean`);
}
cursor.addCursorFlag(flag, value);

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

When it happens

Trigger: cursor.addCursorFlag('tailable', 1); cursor.addCursorFlag('awaitData', 'true'); cursor.addCursorFlag('noCursorTimeout', undefined) where the value was meant to be toggled.

Common situations: 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.

Related errors

• Flag is not one of
• Argument for maxTimeMS must be a number
• Argument "iterator" must be a function
• Invalid read preference
• Operation "batchSize" requires an integer

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/aae0569b8d950001. Report an issue: GitHub.

Appendix: 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 dce7939f86)