mongodb/node-mongodb-native · error · MongoAPIError

RunCommandCursor does not support cursor flags, they must…

Error message

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

What it means

Thrown by RunCommandCursor.addCursorFlag because wire-protocol cursor flags (tailable, awaitData, noCursorTimeout, oplogReplay, exhaust, partial) must be part of the command document sent by runCursorCommand, not applied after construction. The command is frozen at construction time, so the driver rejects this override rather than silently ignoring the flag.

Solutions

Put the flag directly on the command document: db.runCursorCommand({ find: 'coll', filter: {}, tailable: true, awaitData: true }).
Use the tailable/awaitData options of RunCursorCommandOptions at construction: db.runCursorCommand(cmd, { tailable: true, awaitData: true }).
Drop the addCursorFlag call for RunCommandCursor.

Example fix

// before
cursor.addCursorFlag('awaitData', true);

// after
db.runCursorCommand(cmd, { tailable: true, awaitData: true });

Defensive patterns

Strategy: validation

Validate before calling

function buildTailableCommand(cmd, flags) {
  return { ...cmd, ...flags }; // e.g. { tailable: true, awaitData: true }
}
// usage: db.runCursorCommand(buildTailableCommand(cmd, { tailable: true, awaitData: true }))

Type guard

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

Prevention

Set cursor flags on the command document or via RunCursorCommandOptions, not addCursorFlag.
Branch generic cursor setup to skip addCursorFlag for RunCommandCursor.

When it happens

Trigger: Calling cursor.addCursorFlag('tailable', true) or cursor.addCursorFlag('awaitData', true) on a RunCommandCursor; generic cursor setup that sets awaitData for change-like streams.

Common situations: Building a tailable raw-command cursor for change-like streaming; reusing find-cursor setup helpers verbatim.

Related errors

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

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