mongodb/node-mongodb-native · error · MongoAPIError

batchSize must be configured on the command document directl

Error message

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

What it means

For RunCommandCursor the initial command's batchSize must be embedded in the command document; the fluent batchSize() builder is disabled. To control getMore.batchSize, use cursor.setBatchSize().

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

Solutions

1. Add batchSize to the command document: db.runCursorCommand({ ...cmd, batchSize: 100 })
2. For getMore batchSize, call cursor.setBatchSize(100)
3. Branch shared configurators by cursor type

Example fix

// before
db.runCursorCommand(cmd).batchSize(100);
// after
db.runCursorCommand({ ...cmd, batchSize: 100 });

if (cursor instanceof RunCommandCursor) {
  throw new Error('Put batchSize on the command document; use cursor.setBatchSize() for getMore');
}

function isRunCommandCursor(c: AbstractCursor): c is RunCommandCursor {
  return c instanceof RunCommandCursor;
}

When it happens

Trigger: Calling .batchSize(100) on a RunCommandCursor returned by db.runCursorCommand().

Common situations: Porting pagination helpers that called .batchSize() on cursors; reusing generic cursor tuners.

Related errors

• Clone not supported, create a new cursor with db.runCursorCo
• RunCommandCursor does not support readConcern it must be att
• RunCommandCursor does not support cursor flags, they must be
• maxTimeMS must be configured on the command document directl
• Unexpected null session. A cursor creating command should ha

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