mongodb/node-mongodb-native · error · MongoRuntimeError

This method requires a valid operation instance

Error message

This method requires a valid operation instance

What it means

An internal guard inside executeOperation: the operation argument is not an instance of AbstractOperation. Public APIs always wrap user calls into operation objects before reaching here, so a hit indicates either an internal bug, a misuse of the internal executeOperation export, or a stub/mock that does not extend the base class.

Solutions

1. If this is your application code, do not call executeOperation directly — use the public collection/db APIs which build operations for you.
2. If writing tests against internals, ensure your fake operation extends AbstractOperation and implements the required abstract members.
3. Report a driver bug if this surfaces from a normal public API call.

try {
  await executeOperation(client, op);
} catch (e) {
  if (/requires a valid operation instance/.test(e.message)) {
    // this is an internal misuse; report a driver bug if reached from public API
  }
  throw e;
}

When it happens

Trigger: Calling the internal executeOperation(client, someObject) where someObject is a plain object or a mock that does not extend AbstractOperation. Also from test code that builds incomplete operation stubs.

Common situations: Library-internal refactors that bypass the operation factory; tests that mock executeOperation's input shape incorrectly; monkey-patching internal exports.

Related errors

• Option "explain" is not supported on this command
• A collection name must be determined before getMore
• A collection name must be determined before killCursors
• A query document must be specified for query
• An unexpected error type

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

Appendix: source

Thrown at src/operations/execute_operation.ts:71

 *
 * The expectation is that this function:
 * - Connects the MongoClient if it has not already been connected, see {@link autoConnect}
 * - Creates a session if none is provided and cleans up the session it creates
 * - Tries an operation and retries under certain conditions, see {@link executeOperationWithRetries}
 *
 * @typeParam T - The operation's type
 * @typeParam TResult - The type of the operation's result, calculated from T
 *
 * @param client - The MongoClient to execute this operation with
 * @param operation - The operation to execute
 */
export async function executeOperation<
  T extends AbstractOperation,
  TResult = ResultTypeFromOperation<T>
>(client: MongoClient, operation: T, timeoutContext?: TimeoutContext | null): Promise<TResult> {
  if (!(operation instanceof AbstractOperation)) {
    // TODO(NODE-3483): Extend MongoRuntimeError
    throw new MongoRuntimeError('This method requires a valid operation instance');
  }

  const topology =
    client.topology == null
      ? await abortable(autoConnect(client), operation.options)
      : client.topology;

  // The driver sessions spec mandates that we implicitly create sessions for operations
  // that are not explicitly provided with a session.
  let session = operation.session;
  let owner: symbol | undefined;

  if (session == null) {
    owner = Symbol();
    session = client.startSession({ owner, explicit: false });
  } else if (session.hasEnded) {
    throw new MongoExpiredSessionError('Use of expired sessions is not permitted');
  } else if (

View on GitHub (pinned to dce7939f86)