{"id":"62d53291dcdb23a2","repo":"mongodb/node-mongodb-native","slug":"transactions-are-not-supported-in-snapshot-session","errorCode":null,"errorMessage":"Transactions are not supported in snapshot sessions","messagePattern":"Transactions are not supported in snapshot sessions","errorType":"exception","errorClass":"MongoCompatibilityError","httpStatus":null,"severity":"error","filePath":"src/sessions.ts","lineNumber":390,"sourceCode":"\n  /** @returns whether this session is currently in a transaction or not */\n  inTransaction(): boolean {\n    return this.transaction.isActive;\n  }\n\n  /**\n   * Starts a new transaction with the given options.\n   *\n   * @remarks\n   * **IMPORTANT**: Running operations in parallel is not supported during a transaction. The use of `Promise.all`,\n   * `Promise.allSettled`, `Promise.race`, etc to parallelize operations inside a transaction is\n   * undefined behaviour.\n   *\n   * @param options - Options for the transaction\n   */\n  startTransaction(options?: TransactionOptions): void {\n    if (this.snapshotEnabled) {\n      throw new MongoCompatibilityError('Transactions are not supported in snapshot sessions');\n    }\n\n    if (this.inTransaction()) {\n      throw new MongoTransactionError('Transaction already in progress');\n    }\n\n    if (this.isPinned && this.transaction.isCommitted) {\n      this.unpin();\n    }\n\n    this.commitAttempted = false;\n    // increment txnNumber\n    this.incrementTransactionNumber();\n    // create transaction state\n    this.transaction = new Transaction({\n      readConcern:\n        options?.readConcern ??\n        this.defaultTransactionOptions.readConcern ??","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/sessions.ts#L372-L408","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Create a separate non-snapshot session for the transaction: client.startSession() without the snapshot option, then call startTransaction on it.","If snapshot semantics are not required, drop { snapshot: true } from the original startSession options.","Guard the call: if (!session.snapshotEnabled) session.startTransaction()."],"exampleFix":"// before\nconst session = client.startSession({ snapshot: true });\nsession.startTransaction(); // throws\n\n// after\nconst snapshotSession = client.startSession({ snapshot: true }); // for reads\nconst txnSession = client.startSession();                      // for writes\ntxnSession.startTransaction();","handlingStrategy":"validation","validationCode":"if (!session.snapshotEnabled) {\n  session.startTransaction();\n} else {\n  // open a separate non-snapshot session for the transaction\n}","typeGuard":"function canStartTransaction(session: ClientSession): boolean {\n  return !session.snapshotEnabled && !session.inTransaction();\n}","tryCatchPattern":"try {\n  session.startTransaction();\n} catch (e) {\n  if (e instanceof MongoCompatibilityError && /snapshot sessions/.test(e.message)) {\n    // create a fresh non-snapshot session and retry\n  } else throw e;\n}","preventionTips":["Keep snapshot sessions and transaction sessions as distinct startSession() calls.","Centralize session creation in a factory that knows the intended use (read-snapshot vs transactional write).","Add a unit test asserting startTransaction throws on snapshot sessions to lock the contract."],"tags":["sessions","transactions","snapshot","compatibility"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}