mongodb/node-mongodb-native · error · MongoAPIError

Clone not supported, create a new cursor with…

Error message

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

What it means

Thrown by RunCommandCursor.clone() because cloning is intentionally unsupported for raw command cursors. Unlike find/aggregate cursors whose state is reconstructable from declarative options, RunCommandCursor freezes an arbitrary user command document and exposes mutable getMore options, so a deep clone would silently diverge from the original command. Re-create the cursor from db.runCursorCommand instead.

Solutions

Re-create the cursor: const c2 = db.runCursorCommand(cmd, opts) instead of cursor.clone().
Iterate the same cursor once and buffer results if you need two passes.
Remove the clone() call from generic cursor handling when the cursor is a RunCommandCursor.

Example fix

// before
const c2 = cursor.clone();

// after
const c2 = db.runCursorCommand(cursor.command, originalOptions);

Defensive patterns

Strategy: type-guard

Validate before calling

function cloneOrRecreate(db, cursor, cmd, opts) {
  if (cursor instanceof RunCommandCursor) return db.runCursorCommand(cmd, opts);
  return cursor.clone();
}

Type guard

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

Prevention

Branch generic cursor utilities to recreate rather than clone RunCommandCursor.
Store the original command+options when you may need a second cursor.

When it happens

Trigger: Calling cursor.clone() on a RunCommandCursor returned by db.runCursorCommand(cmd, opts); generic code that clones every cursor before iteration; sharing a cursor across two consumers via clone().

Common situations: Generic cursor-pooling utilities that clone defensively; refactoring from find().clone() patterns to runCursorCommand without updating the clone call.

Related errors

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

Appendix: 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 dce7939f86)