mongodb/node-mongodb-native · critical · MongoRuntimeError

This method requires a valid operation instance

Error message

This method requires a valid operation instance

What it means

executeOperation (src/operations/execute_operation.ts:71) guards its entry point by verifying the `operation` argument is an instance of AbstractOperation. If it is not, a MongoRuntimeError is thrown. This protects the internal execution pipeline from malformed input and indicates a programming error rather than a runtime/server condition.

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 3366c21a63)

Solutions

1. If you are using the public collection/db API, this error should not occur — verify you are not passing a hand-rolled object to an internal function.
2. If extending the driver, ensure your operation class extends AbstractOperation and is instantiated, not passed as a plain object.
3. Report a driver bug if this surfaces during normal library usage.

Example fix

// before (incorrect internal usage)
await executeOperation(client, { commandName: 'find', filter: {} });

// after
import { FindOperation } from './operations/find';
const op = new FindOperation(namespace, filter, options);
await executeOperation(client, op);

import { AbstractOperation } from 'mongodb';
function assertOperation(op: unknown): asserts op is AbstractOperation {
  if (!(op instanceof AbstractOperation)) {
    throw new TypeError('Expected an AbstractOperation instance');
  }
}

import { AbstractOperation } from 'mongodb';
const isAbstractOperation = (op: unknown): op is AbstractOperation =>
  op instanceof AbstractOperation;

When it happens

Trigger: Directly calling the internal executeOperation() helper with a plain object, a class that does not extend AbstractOperation, or undefined/null. End users calling the public API (collection.find, etc.) will never trigger this.

Common situations: Custom driver extensions or test code that constructs operation objects incorrectly, or accidental passing of a non-operation value when mocking internals.

Related errors

• Attempted to get an access token when none exists.
• Attempted to get a refresh token when none exists.
• Attempted to get IDP information when none exists.
• client.connect did not create a topology but also did not th
• Operation passed in cannot be an Array

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/c7bf97269569b6c6.json. Report an issue: GitHub.