Why does the MongoDB driver's withTransaction() helper exist instead of calling commitTransaction() yourself?

## The raw API A multi-document transaction lives inside a **client session** — a logical handle the driver uses to tie operations together and to attach a transaction number the server can recognise. The manual sequence is: ```javascript const session = client.startSession(); try { session.startTransaction({ readConcern: { level: "snapshot" }, writeConcern: { w: "majority" } }); await accounts.updateOne({_id: from}, {$inc: {balance: -100}}, { session }); await accounts.updateOne({_id: to}, {$inc: {balance: 100}}, { session }); await session.commitTransaction(); } catch (e) { await session.abortTransaction(); throw e; } finally { await session.endSession(); } ``` Every operation must be given the session. This is the single most common bug in hand-rolled code: an operation without `{ session }` executes as an ordinary write outside the transaction, is visible immediately, and is *not* undone when the transaction aborts. There is no error and no warning — the write simply is not part of the transaction. ## The two retryable failure classes What makes the manual version hard is not the happy path, it is the errors. The server tags errors with labels, and two of them are contracts with the driver: **`TransientTransactionError`** — the transaction cannot continue, but nothing it did is visible and the *whole* transaction can be re-run from the start. The usual causes are a write conflict with a concurrent transaction (MongoDB fails these fast rather than waiting), a primary stepdown or election, or a transaction that has already been aborted by the server. The correct response is: start a new transaction and run all the work again. **`UnknownTransactionCommitResult`** — you sent `commitTransaction()` and did not learn the outcome, typically a network error or a `maxCommitTimeMS` timeout. The transaction may or may not have committed. Re-sending `commitTransaction()` on the same session is safe: if it committed, the server reports success again; if it did not, the commit is attempted. The correct response is to retry the *commit only*, not the whole callback. Getting this right by hand means two nested loops with different retry units and careful label inspection. Most hand-written implementations either retry nothing (turning ordinary elections into user-visible errors) or retry everything (re-running work after a commit that actually succeeded). ## What withTransaction() does `session.withTransaction(callback, options)` wraps all of it: it starts the transaction, runs your callback, commits, retries the callback on `TransientTransactionError`, retries the commit on `UnknownTransactionCommitResult`, and aborts on any error it cannot retry. It stops retrying after a limit of about 120 seconds so a permanently conflicting workload fails rather than spinning forever. Transaction options — read concern, write concern, read preference, `maxCommitTimeMS` — are passed to the helper rather than to `startTransaction()`. ## The contract on your callback Because the callback can run several times, it must be written as re-runnable work: - **No external side effects.** Sending an email, charging a card, publishing to a queue or mutating shared in-memory state inside the callback means doing it once per attempt. Collect the intent inside the transaction (an outbox document, say) and perform the effect after the helper returns. - **Pass the session to every operation**, including reads you rely on. - **Do not swallow errors.** A `try/catch` inside the callback that logs and returns hides the label and defeats the retry. - **Do not commit or abort inside the callback** unless you deliberately want to end the retry loop. - **Keep it short.** Every attempt runs against the server's transaction time limit, and long callbacks hold a snapshot and locks the whole time. ## Other rules worth knowing Reads in a transaction are served from the primary — read preference must be primary, and requesting a secondary is an error. The transaction's read concern and write concern are set once for the transaction and apply to the whole thing, not per operation. MongoDB 4.4 and later allow creating a collection or an index inside a transaction, with restrictions; other catalog operations remain off-limits. Operations against the `admin`, `config` and `local` databases are not transactional. ## What an interviewer is listening for The weak answer is "it's just convenience." The strong answer names the two error labels, says what the retry *unit* is for each, and states the callback contract — because that contract is where real systems break: the retry silently doubles an outbound call, or an operation missing its session escapes the transaction entirely.