mongodb/node-mongodb-native · error · MongoAPIError

batchSize must be configured on the command document…

Error message

batchSize must be configured on the command document directly, to configure getMore.batchSize use cursor.setBatchSize()

What it means

Thrown by RunCommandCursor.batchSize because the inherited method would set batchSize for the initial cursor-creating command, but the command document is frozen and sent verbatim. The initial batchSize must live on the command; getMore.batchSize is set via cursor.setBatchSize. The override prevents a silent no-op.

Solutions

For the initial command: put batchSize on the command document, db.runCursorCommand({ find: 'coll', filter: {}, batchSize: 100 }).
For getMore.batchSize: call cursor.setBatchSize(100) which sets getMoreOptions.batchSize.
Drop the inherited batchSize() call on RunCommandCursor.

Example fix

// before
cursor.batchSize(100);

// after
db.runCursorCommand({ find: 'coll', filter: {}, cursor: { batchSize: 100 } });
// or for getMore:
cursor.setBatchSize(100);

Defensive patterns

Strategy: validation

Validate before calling

function applyBatchSize(db, cursor, cmd, size, scope) {
  if (scope === 'getMore') return cursor.setBatchSize(size);
  return db.runCursorCommand({ ...cmd, cursor: { ...(cmd.cursor ?? {}), batchSize: size } });
}

Type guard

function isRunCommandCursor(cursor) { return cursor instanceof RunCommandCursor; }

Prevention

Put initial batchSize on the command document (cursor: { batchSize }).
Use cursor.setBatchSize only for getMore.batchSize on tailable-await streams.

When it happens

Trigger: Calling cursor.batchSize(100) on a RunCommandCursor; generic cursor setup that sets batchSize on every cursor; tuning batch sizes for a runCursorCommand stream.

Common situations: Sharing cursor-tuning helpers across find/aggregate/runCommand; refactoring from find().batchSize() patterns.

Related errors

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

Appendix: source

Thrown at src/cursor/run_command_cursor.ts:129

  /** Unsupported for RunCommandCursor: various cursor flags must be configured directly on command document */
  public override addCursorFlag(_: string, __: boolean): never {
    throw new MongoAPIError(
      'RunCommandCursor does not support cursor flags, they must be attached to the command being run'
    );
  }

  /**
   * Unsupported for RunCommandCursor: maxTimeMS must be configured directly on command document
   */
  public override maxTimeMS(_: number): never {
    throw new MongoAPIError(
      'maxTimeMS must be configured on the command document directly, to configure getMore.maxTimeMS use cursor.setMaxTimeMS()'
    );
  }

  /** Unsupported for RunCommandCursor: batchSize must be configured directly on command document */
  public override batchSize(_: number): never {
    throw new MongoAPIError(
      'batchSize must be configured on the command document directly, to configure getMore.batchSize use cursor.setBatchSize()'
    );
  }

  /** @internal */
  private db: Db;

  /** @internal */
  constructor(db: Db, command: Document, options: RunCursorCommandOptions = {}) {
    super(db.client, ns(db.namespace), options);
    this.db = db;
    this.command = Object.freeze({ ...command });
  }

  /** @internal */
  protected async _initialize(session: ClientSession): Promise<InitialCursorResponse> {
    const operation = new RunCursorCommandOperation(this.db.s.namespace, this.command, {
      ...this.cursorOptions,

View on GitHub (pinned to dce7939f86)