mongodb/node-mongodb-native · error · MongoCompatibilityError

Transactions are not supported in snapshot sessions

Error message

Transactions are not supported in snapshot sessions

What it means

Snapshot sessions provide a consistent read view of the data at a single point in time and cannot host a transaction. `startTransaction` checks `this.snapshotEnabled` (set when `startSession({ snapshot: true })`) and throws MongoCompatibilityError.

Solutions

1. Use a separate non-snapshot session for transactions: `client.startSession()` (no `snapshot: true`).
2. Design helpers to accept the session from the caller so snapshot vs. transaction sessions are not mixed.
3. If you need both, create two sessions with appropriate options.

Example fix

// before
const session = client.startSession({ snapshot: true });
session.startTransaction();

// after
const readSession = client.startSession({ snapshot: true });
const txnSession = client.startSession();
txnSession.startTransaction();

function txnSession(client) {
  // do not enable snapshot for transaction-capable sessions
  return client.startSession();
}

When it happens

Trigger: `const session = client.startSession({ snapshot: true }); session.startTransaction();` — also reachable inside `withTransaction` if the session was created with snapshot mode.

Common situations: Reusing a session object across both snapshot reads and write transactions; generic helper that always calls `startSession({ snapshot: true })` and later tries to wrap writes in a transaction.

Related errors

• Snapshot reads require MongoDB 5.0 or later
• Cannot call abortTransaction after calling commitTransaction
• Cannot call abortTransaction twice
• Cannot call commitTransaction after calling abortTransaction
• Current topology does not support sessions

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

Appendix: source

Thrown at src/sessions.ts:390

  /** @returns whether this session is currently in a transaction or not */
  inTransaction(): boolean {
    return this.transaction.isActive;
  }

  /**
   * Starts a new transaction with the given options.
   *
   * @remarks
   * **IMPORTANT**: Running operations in parallel is not supported during a transaction. The use of `Promise.all`,
   * `Promise.allSettled`, `Promise.race`, etc to parallelize operations inside a transaction is
   * undefined behaviour.
   *
   * @param options - Options for the transaction
   */
  startTransaction(options?: TransactionOptions): void {
    if (this.snapshotEnabled) {
      throw new MongoCompatibilityError('Transactions are not supported in snapshot sessions');
    }

    if (this.inTransaction()) {
      throw new MongoTransactionError('Transaction already in progress');
    }

    if (this.isPinned && this.transaction.isCommitted) {
      this.unpin();
    }

    this.commitAttempted = false;
    // increment txnNumber
    this.incrementTransactionNumber();
    // create transaction state
    this.transaction = new Transaction({
      readConcern:
        options?.readConcern ??
        this.defaultTransactionOptions.readConcern ??

View on GitHub (pinned to dce7939f86)