{"record":{"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":"error","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/dce7939f86fb283e167ad709955abedb7bf23124/src/operations/execute_operation.ts#L53-L89","documentation":"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.","triggerScenarios":"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.","commonSituations":"Library-internal refactors that bypass the operation factory; tests that mock executeOperation's input shape incorrectly; monkey-patching internal exports.","solutions":["If this is your application code, do not call executeOperation directly — use the public collection/db APIs which build operations for you.","If writing tests against internals, ensure your fake operation extends AbstractOperation and implements the required abstract members.","Report a driver bug if this surfaces from a normal public API call."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await executeOperation(client, op);\n} catch (e) {\n  if (/requires a valid operation instance/.test(e.message)) {\n    // this is an internal misuse; report a driver bug if reached from public API\n  }\n  throw e;\n}","preventionTips":["Avoid calling the internal executeOperation from application code.","When testing operations, extend AbstractOperation rather than passing plain stubs."],"tags":["internal","operations","api-misuse"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}