{"id":"c7bf97269569b6c6","repo":"mongodb/node-mongodb-native","slug":"this-method-requires-a-valid-operation-instance","errorCode":null,"errorMessage":"This method requires a valid operation instance","messagePattern":"This method requires a valid operation instance","errorType":"exception","errorClass":"MongoRuntimeError","httpStatus":null,"severity":"critical","filePath":"src/operations/execute_operation.ts","lineNumber":71,"sourceCode":" *\n * The expectation is that this function:\n * - Connects the MongoClient if it has not already been connected, see {@link autoConnect}\n * - Creates a session if none is provided and cleans up the session it creates\n * - Tries an operation and retries under certain conditions, see {@link executeOperationWithRetries}\n *\n * @typeParam T - The operation's type\n * @typeParam TResult - The type of the operation's result, calculated from T\n *\n * @param client - The MongoClient to execute this operation with\n * @param operation - The operation to execute\n */\nexport async function executeOperation<\n  T extends AbstractOperation,\n  TResult = ResultTypeFromOperation<T>\n>(client: MongoClient, operation: T, timeoutContext?: TimeoutContext | null): Promise<TResult> {\n  if (!(operation instanceof AbstractOperation)) {\n    // TODO(NODE-3483): Extend MongoRuntimeError\n    throw new MongoRuntimeError('This method requires a valid operation instance');\n  }\n\n  const topology =\n    client.topology == null\n      ? await abortable(autoConnect(client), operation.options)\n      : client.topology;\n\n  // The driver sessions spec mandates that we implicitly create sessions for operations\n  // that are not explicitly provided with a session.\n  let session = operation.session;\n  let owner: symbol | undefined;\n\n  if (session == null) {\n    owner = Symbol();\n    session = client.startSession({ owner, explicit: false });\n  } else if (session.hasEnded) {\n    throw new MongoExpiredSessionError('Use of expired sessions is not permitted');\n  } else if (","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/operations/execute_operation.ts#L53-L89","documentation":"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.","triggerScenarios":"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.","commonSituations":"Custom driver extensions or test code that constructs operation objects incorrectly, or accidental passing of a non-operation value when mocking internals.","solutions":["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.","If extending the driver, ensure your operation class extends AbstractOperation and is instantiated, not passed as a plain object.","Report a driver bug if this surfaces during normal library usage."],"exampleFix":"// before (incorrect internal usage)\nawait executeOperation(client, { commandName: 'find', filter: {} });\n\n// after\nimport { FindOperation } from './operations/find';\nconst op = new FindOperation(namespace, filter, options);\nawait executeOperation(client, op);","handlingStrategy":"validation","validationCode":"import { AbstractOperation } from 'mongodb';\nfunction assertOperation(op: unknown): asserts op is AbstractOperation {\n  if (!(op instanceof AbstractOperation)) {\n    throw new TypeError('Expected an AbstractOperation instance');\n  }\n}","typeGuard":"import { AbstractOperation } from 'mongodb';\nconst isAbstractOperation = (op: unknown): op is AbstractOperation =>\n  op instanceof AbstractOperation;","tryCatchPattern":null,"preventionTips":["Do not call the internal executeOperation helper directly with plain objects.","Always instantiate the correct Operation subclass when extending the driver.","If this surfaces during normal public-API usage, file a driver bug."],"tags":["internal","invariant","programming-error"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}