{"id":"5fb465a77a22e59e","repo":"mongodb/node-mongodb-native","slug":"attempted-illegal-state-transition-from-this-st","errorCode":null,"errorMessage":"Attempted illegal state transition from [${this.state}] to [${nextState}]","messagePattern":"Attempted illegal state transition from \\[(.+?)\\] to \\[(.+?)\\]","errorType":"exception","errorClass":"MongoRuntimeError","httpStatus":null,"severity":"error","filePath":"src/transactions.ts","lineNumber":163,"sourceCode":"  /**\n   * Transition the transaction in the state machine\n   * @param nextState - The new state to transition to\n   */\n  transition(nextState: TxnState): void {\n    const nextStates = stateMachine[this.state];\n    if (nextStates && nextStates.includes(nextState)) {\n      this.state = nextState;\n      if (\n        this.state === TxnState.NO_TRANSACTION ||\n        this.state === TxnState.STARTING_TRANSACTION ||\n        this.state === TxnState.TRANSACTION_ABORTED\n      ) {\n        this.unpinServer();\n      }\n      return;\n    }\n\n    throw new MongoRuntimeError(\n      `Attempted illegal state transition from [${this.state}] to [${nextState}]`\n    );\n  }\n\n  pinServer(server: Server): void {\n    if (this.isActive) {\n      this._pinnedServer = server;\n    }\n  }\n\n  unpinServer(): void {\n    this._pinnedServer = undefined;\n  }\n}\n\nexport function isTransactionCommand(command: Document): boolean {\n  return !!(command.commitTransaction || command.abortTransaction);\n}","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/transactions.ts#L145-L181","documentation":"Thrown by the @internal Transaction.transition() when the requested state change is not allowed by the transaction state machine. The state machine only permits specific transitions (e.g. NO_TRANSACTION -> STARTING_TRANSACTION, TRANSACTION_IN_PROGRESS -> COMMITTED/ABORTED); any other pairing throws MongoRuntimeError with both the current and target states in the message.","triggerScenarios":"Driver-internal logic attempting a forbidden transition, e.g. trying to go from TRANSACTION_COMMITTED back to TRANSACTION_IN_PROGRESS, or from NO_TRANSACTION directly to TRANSACTION_IN_PROGRESS. Usually surfaces when the public API is called in an unexpected order that the per-method guards did not catch first.","commonSituations":"Driver bugs in transaction lifecycle handling; rare interleavings with retries/CSOT; concurrent use of one session from multiple async tasks (which the driver explicitly does not support).","solutions":["Ensure no two async operations share the same ClientSession concurrently - serialize all work on a session.","Use withTransaction() rather than manual start/commit/abort to keep transitions in-spec.","If the call sequence is correct and you still hit this, report a driver bug on the NODE Jira project with the full sequence and states shown in the message."],"exampleFix":"// before - concurrent session use produces illegal transitions\nawait Promise.all([\n  coll.insertOne(a, { session }),\n  coll.insertOne(b, { session }) // same session, parallel -> illegal state\n]);\n\n// after - serialize operations on the session\nawait coll.insertOne(a, { session });\nawait coll.insertOne(b, { session });","handlingStrategy":"try-catch","validationCode":"// serialize all work on a session - never share it across concurrent ops\nfor (const doc of docs) {\n  await coll.insertOne(doc, { session }); // sequential, not Promise.all\n}","typeGuard":null,"tryCatchPattern":"try {\n  session.startTransaction();\n  await runOps(session);\n  await session.commitTransaction();\n} catch (e) {\n  if (e instanceof MongoRuntimeError && /illegal state transition/.test(e.message)) {\n    // reset by aborting if possible and starting fresh, or report a driver bug\n    if (session.inTransaction()) await session.abortTransaction();\n  } else throw e;\n}","preventionTips":["Never run two operations concurrently on the same ClientSession; serialize them.","Use withTransaction() to keep transitions spec-compliant.","Report persistent occurrences as a driver bug with the from/to states from the message."],"tags":["transactions","state-machine","internal","runtime","concurrency"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}