{"record":{"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/dce7939f86fb283e167ad709955abedb7bf23124/src/transactions.ts#L145-L181","documentation":"Thrown by Transaction.transition() when the requested next state is not in the allowed transitions from the current state, as defined in the stateMachine table (e.g. you cannot go from TRANSACTION_IN_PROGRESS directly to NO_TRANSACTION). The driver manages these transitions internally during startTransaction/commit/abort; reaching this error means an invalid sequence was attempted.","triggerScenarios":"Internally, calling commitTransaction on an already-aborted transaction, or startTransaction after commit without proper reset. User code that manually invokes internal session/transaction methods in the wrong order, or concurrent commit/abort on the same session.","commonSituations":"Calling session.commitTransaction() after session.abortTransaction() has already run, or starting a new transaction on a session without properly ending the previous one. Usually indicates application logic errors in transaction lifecycle management.","solutions":["Review your transaction lifecycle: ensure startTransaction -> operations -> commitTransaction (or abortTransaction) sequence is correct.","Do not call commitTransaction after abortTransaction; the transaction is already ended.","Avoid running concurrent operations that mutate the same session's transaction state."],"exampleFix":"// before\nsession.startTransaction();\nsession.abortTransaction();\nsession.commitTransaction(); // throws: already aborted\n\n// after\nsession.startTransaction();\ntry {\n  await session.commitTransaction();\n} catch {\n  await session.abortTransaction();\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"session.startTransaction();\ntry {\n  // ... operations ...\n  await session.commitTransaction();\n} catch (e) {\n  if (session.inTransaction()) await session.abortTransaction();\n  if (!(e instanceof MongoRuntimeError && /illegal state transition/.test(e.message))) throw e;\n}","preventionTips":["Always follow startTransaction with either commitTransaction or abortTransaction, never both.","Do not commit/abort the same transaction twice.","Avoid concurrent operations that mutate the same session's transaction state."],"tags":["transaction","state-machine","internal"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}