mongodb/node-mongodb-native · error · MongoAPIError

RunCommandCursor does not support cursor flags, they must be

Error message

RunCommandCursor does not support cursor flags, they must be attached to the command being run

What it means

RunCommandCursor runs an opaque command document, so per-cursor wire flags (tailable, awaitData, noCursorTimeout, etc.) cannot be set via addCursorFlag(). They must be expressed as top-level fields of the command document, or for tailable/awaitData via the constructor options.

Source

Thrown at src/cursor/run_command_cursor.ts:113

    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
   */
  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()'
    );

View on GitHub (pinned to 3366c21a63)

Solutions

1. Set tailable/awaitData via the options argument to db.runCursorCommand
2. Add the flag as a top-level field on the command document
3. Special-case RunCommandCursor in shared cursor configuration code

Example fix

// before
cursor.addCursorFlag('noCursorTimeout', true);
// after
const cursor = db.runCursorCommand({ ...cmd, noCursorTimeout: true });

if (cursor instanceof RunCommandCursor) {
  throw new Error('Use the command document or constructor options for cursor flags');
}

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

When it happens

Trigger: Calling .addCursorFlag('noCursorTimeout', true) or .addCursorFlag('tailable', true) on a RunCommandCursor.

Common situations: Generic cursor tuners that flip flags; converting change-stream-like tailing code to runCursorCommand.

Related errors

• Clone not supported, create a new cursor with db.runCursorCo
• RunCommandCursor does not support readConcern it must be att
• 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/1abbad61bc0c84b4.json. Report an issue: GitHub.