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

Thrown by ClientSession.startTransaction() when the session was created with snapshotEnabled=true. Snapshot sessions provide a consistent read view across reads and are mutually exclusive with multi-document transactions per the MongoDB sessions specification. It surfaces as a MongoCompatibilityError.

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 3366c21a63)

Solutions

1. Create a separate non-snapshot session for the transaction: client.startSession() without the snapshot option, then call startTransaction on it.
2. If snapshot semantics are not required, drop { snapshot: true } from the original startSession options.
3. Guard the call: if (!session.snapshotEnabled) session.startTransaction().

Example fix

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

// after
const snapshotSession = client.startSession({ snapshot: true }); // for reads
const txnSession = client.startSession();                      // for writes
txnSession.startTransaction();

if (!session.snapshotEnabled) {
  session.startTransaction();
} else {
  // open a separate non-snapshot session for the transaction
}

function canStartTransaction(session: ClientSession): boolean {
  return !session.snapshotEnabled && !session.inTransaction();
}

try {
  session.startTransaction();
} catch (e) {
  if (e instanceof MongoCompatibilityError && /snapshot sessions/.test(e.message)) {
    // create a fresh non-snapshot session and retry
  } else throw e;
}

When it happens

Trigger: Calling session.startTransaction() on a session obtained from client.startSession({ snapshot: true }). Also indirectly via withTransaction() on such a session, since withTransaction calls startTransaction internally.

Common situations: Reusing a snapshot-capable session for a transactional write path; library code that always starts transactions on a pooled session without checking its options; upgrading code that mixed snapshot reads and writes.

Related errors

• Current topology does not support sessions
• Snapshot reads require MongoDB 5.0 or later
• Transaction already in progress
• No transaction started
• Cannot call commitTransaction after calling abortTransaction

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/62d53291dcdb23a2.json. Report an issue: GitHub.