mongodb/node-mongodb-native · error · MongoRuntimeError

Attempted illegal state transition from

Error message

Attempted illegal state transition from [${this.state}] to [${nextState}]

What it means

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.

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.

Example fix

// before
session.startTransaction();
session.abortTransaction();
session.commitTransaction(); // throws: already aborted

// after
session.startTransaction();
try {
  await session.commitTransaction();
} catch {
  await session.abortTransaction();
}

Defensive patterns

Strategy: try-catch

Try / catch

session.startTransaction();
try {
  // ... operations ...
  await session.commitTransaction();
} catch (e) {
  if (session.inTransaction()) await session.abortTransaction();
  if (!(e instanceof MongoRuntimeError && /illegal state transition/.test(e.message))) throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/5fb465a77a22e59e. Report an issue: GitHub.

Appendix: source

Thrown at src/transactions.ts:163

  /**
   * Transition the transaction in the state machine
   * @param nextState - The new state to transition to
   */
  transition(nextState: TxnState): void {
    const nextStates = stateMachine[this.state];
    if (nextStates && nextStates.includes(nextState)) {
      this.state = nextState;
      if (
        this.state === TxnState.NO_TRANSACTION ||
        this.state === TxnState.STARTING_TRANSACTION ||
        this.state === TxnState.TRANSACTION_ABORTED
      ) {
        this.unpinServer();
      }
      return;
    }

    throw new MongoRuntimeError(
      `Attempted illegal state transition from [${this.state}] to [${nextState}]`
    );
  }

  pinServer(server: Server): void {
    if (this.isActive) {
      this._pinnedServer = server;
    }
  }

  unpinServer(): void {
    this._pinnedServer = undefined;
  }
}

export function isTransactionCommand(command: Document): boolean {
  return !!(command.commitTransaction || command.abortTransaction);
}

View on GitHub (pinned to dce7939f86)