mongodb/node-mongodb-native · error · MongoInvalidArgumentError

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

Error message

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

What it means

Thrown by cursor.addCursorFlag(flag, value) when flag is not one of CURSOR_FLAGS = ['tailable','oplogReplay','noCursorTimeout','awaitData','exhaust','partial']. The driver only allows the documented set of wire-protocol cursor flags.

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 3366c21a63)

Solutions

1. Use only one of the six CURSOR_FLAGS. Prefer setting these via find() options (e.g. { tailable: true }) instead of addCursorFlag.
2. Check the exact spelling and case against CURSOR_FLAGS.
3. If the flag you want is not in the list, it is probably a query option, not a cursor flag.

Example fix

// before
cursor.addCursorFlag('noTimeout', true);
// after
cursor.addCursorFlag('noCursorTimeout', true);

import { CURSOR_FLAGS } from 'mongodb';
if (!CURSOR_FLAGS.includes(flag)) throw new Error(`bad flag ${flag}`);

import { CURSOR_FLAGS } from 'mongodb';
function isCursorFlag(f): f is typeof CURSOR_FLAGS[number] {
  return (CURSOR_FLAGS as readonly string[]).includes(f);
}

When it happens

Trigger: Calling addCursorFlag('noCursorTimeout') correctly works, but addCursorFlag('noTimeout'), addCursorFlag('maxTimeMS'), addCursorFlag('sort'), or any invented name throws. Also case mistakes like 'Tailable'.

Common situations: Confusing query options (sort, limit, batchSize) with cursor flags; pluralizing or abbreviating a flag name; using a name from another driver.

Related errors

• Tailable cursor does not support batchSize
• Option 'mongodbLogPath' must be of type 'stderr' | 'stdout'
• Option 'mongodbLogComponentSeverities' must be a non-null ob
• Cursor must be constructed with MongoClient
• Cannot specify maxAwaitTimeMS >= timeoutMS for a tailable aw

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