mongodb/node-mongodb-native · error · MongoAPIError

Clone not supported, create a new cursor with db.runCursorCo

Error message

Clone not supported, create a new cursor with db.runCursorCommand

What it means

RunCommandCursor deliberately overrides clone() to throw because the cursor wraps an arbitrary user-supplied command that the driver cannot safely re-execute or fork. Each RunCommandCursor owns a frozen command and a single execution lifecycle, so obtaining an independent cursor requires invoking db.runCursorCommand() again.

Source

Thrown at src/cursor/run_command_cursor.ts:101

   * @param maxTimeMS - the number of milliseconds to wait for new data
   */
  public setMaxTimeMS(maxTimeMS: number): this {
    this.getMoreOptions.maxAwaitTimeMS = maxTimeMS;
    return this;
  }

  /**
   * Controls the `getMore.batchSize` field
   * @param batchSize - the number documents to return in the `nextBatch`
   */
  public setBatchSize(batchSize: number): this {
    this.getMoreOptions.batchSize = batchSize;
    return this;
  }

  /** Unsupported for RunCommandCursor */
  public override clone(): never {
    throw new MongoAPIError('Clone not supported, create a new cursor with db.runCursorCommand');
  }

  /** Unsupported for RunCommandCursor: readConcern must be configured directly on command document */
  public override withReadConcern(_: ReadConcernLike): never {
    throw new MongoAPIError(
      'RunCommandCursor does not support readConcern it must be attached to the command being run'
    );
  }

  /** 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

View on GitHub (pinned to 3366c21a63)

Solutions

1. Replace cursor.clone() with a fresh db.runCursorCommand(cursor.command) call
2. Keep the original command document and re-invoke runCursorCommand for each independent iteration
3. Branch generic cursor helpers to skip clone() for RunCommandCursor instances

Example fix

// before
const c2 = cursor.clone();
// after
const c2 = db.runCursorCommand(cursor.command);

if (cursor instanceof RunCommandCursor) {
  throw new Error('RunCommandCursor cannot be cloned; call db.runCursorCommand again');
}

import { RunCommandCursor } from 'mongodb';
function isCloneable(cursor: AbstractCursor): boolean {
  return !(cursor instanceof RunCommandCursor);
}

When it happens

Trigger: Calling .clone() on a cursor returned by db.runCursorCommand(cmd). This usually happens when porting generic cursor utilities that worked against FindCursor/AggregationCursor.

Common situations: Migrating find()-based helpers to runCursorCommand(); shared middleware that normalizes cursors via clone(); code that assumed every AbstractCursor supports clone().

Related errors

• 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
• batchSize 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/3ea6d0a57f7f5a53.json. Report an issue: GitHub.