mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Flag is not one of

Error message

Flag ${flag} is not one of ${CURSOR_FLAGS}

What it means

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.

Solutions

1. Use one of the exact CURSOR_FLAGS names: 'tailable', 'oplogReplay', 'noCursorTimeout', 'awaitData', 'exhaust', 'partial'.
2. For options that are not wire flags (timeout, comment, batchSize), use the corresponding cursor method or the options object instead.
3. Add a TypeScript annotation so the compiler rejects invalid flag names: addCursorFlag(flag: CursorFlag, value: boolean).

Example fix

// before: typo, not a real wire flag
cursor.addCursorFlag('await', true);

// after: use the exact flag name
cursor.addCursorFlag('awaitData', true);

const VALID_FLAGS = ['tailable','oplogReplay','noCursorTimeout','awaitData','exhaust','partial'] as const;
if (!VALID_FLAGS.includes(flag as any)) {
  throw new RangeError(`Invalid cursor flag: ${flag}`);
}

import { CURSOR_FLAGS, type CursorFlag } from 'mongodb';
function isCursorFlag(v: unknown): v is CursorFlag {
  return typeof v === 'string' && (CURSOR_FLAGS as readonly string[]).includes(v);
}

When it happens

Trigger: cursor.addCursorFlag('await', true) (typo for awaitData); cursor.addCursorFlag('timeout', true) (not a wire flag); cursor.addCursorFlag('partialResults', true) (correct name is 'partial').

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

Related errors

• Flag must be a boolean value
• 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/382848471a76f5f6. Report an issue: GitHub.

Appendix: source

Thrown at src/cursor/abstract_cursor.ts:681

        // Note: previous versions of this logic used `array.push(...)`, which adds each item
        // to the callstack.  For large arrays, this can exceed the maximum call size.
        for (const doc of docs) {
          array.push(doc);
        }
      }
    }
    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

View on GitHub (pinned to dce7939f86)