错误处理和重试逻辑

MongoDB transactions can fail with transient errors—temporary conditions like network blips, primary failovers, or write conflicts—that do not indicate a logical problem with your code. These errors are safe to retry: the transaction was rolled back cleanly, and retrying it will produce correct results. Without retry logic, your application will surface unnecessary errors to users for conditions that a simple retry would resolve.

MongoDB classifies transaction errors with two important error labels: TransientTransactionError and UnknownTransactionCommitResult. TransientTransactionError means the entire transaction failed and it is safe to retry from the beginning. UnknownTransactionCommitResult means the commit was sent but the client does not know if it succeeded—the commit must be retried (not the whole transaction). Each requires a different retry strategy.

TransientTransactionError occurs when a transaction cannot proceed due to temporary conditions: write conflicts (another transaction modified the same document first), lock acquisition timeouts, replica set election failovers, or network connectivity issues. MongoDB rolls back the transaction completely before returning this error. The safe response is to start over with a fresh session and re-execute all operations.

UnknownTransactionCommitResult happens when a network timeout or failover occurs after MongoDB has committed the transaction but before the acknowledgment reaches the client. The transaction may or may not have been committed. The correct response is to retry only commitTransaction()—not the whole transaction—because MongoDB detects duplicate commit calls on the same session and returns successfully if the transaction is already committed.

MongoDB's documentation specifies a two-loop retry pattern: an outer loop that retries the entire transaction on TransientTransactionError, and an inner loop that retries only the commit on UnknownTransactionCommitResult. This pattern handles all transient failure modes correctly and is what the withTransaction() helper implements internally.

The commit retry loop handles UnknownTransactionCommitResult. It continuously calls commitTransaction() until either the commit is confirmed or a non-retryable error occurs. MongoDB idempotently handles duplicate commit calls on the same transaction—if the transaction was already committed, the retry returns success without re-applying the writes.

Combining both retry loops gives the complete production-grade transaction function. The business logic is extracted into a separate function passed as a parameter, keeping the retry scaffolding reusable. Notice that the session is reused across retries—you do not create a new session for each retry, but you must call startTransaction() again at the beginning of each attempt.

The session.withTransaction(callback, options) helper implements the two-loop retry pattern automatically. You provide only the business logic callback and transaction options. Using withTransaction dramatically reduces boilerplate, minimizes the risk of getting the retry logic wrong, and is the recommended approach for all production MongoDB transaction code in the Node.js driver.

Not every error inside a transaction is transient and retryable. Application-level errors—like insufficient funds, duplicate username, or invalid input—should abort the transaction and return an error to the user, not retry. Only errors with the TransientTransactionError or UnknownTransactionCommitResult labels should trigger retries. Mix both types of error handling in your transaction callback: throw domain errors that the outer layer can check before retrying.

Write conflicts occur when two transactions try to modify the same document simultaneously. MongoDB uses optimistic locking—it allows both transactions to proceed until commit time, then aborts the one that conflicts. The aborted transaction receives a TransientTransactionError with code WriteConflict. This is expected behavior—not a bug—and the retry loop handles it correctly. Frequent write conflicts indicate a hot document that may need schema redesign.

In a production retry loop, always enforce a maximum number of retries to prevent infinite loops in pathological scenarios (e.g., perpetual write conflicts on a very hot document). After the maximum attempts, throw the last error so the application can handle it gracefully. Include exponential backoff with jitter between retries to reduce contention from multiple clients simultaneously retrying the same transaction.

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

In this lesson you learned: TransientTransactionError means retry the entire transaction from the start, UnknownTransactionCommitResult means retry only the commit call, and withTransaction() implements this two-loop retry pattern automatically and is the recommended production approach. Next up we explore transaction performance considerations and how to minimize their overhead.