Transaction Anti-Patterns
Parent: MongoDB Transactions · Published reference · snapshot 2026-10-20 · skill ranked-3a018e98 · viability 4.25 / 5 (research)
↓ Facts as markdownall context files
Source-anchored research for Transaction Anti-Patterns. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- When a consistency invariant can be enforced within one document, prefer a schema and atomic single-document write that enforce it; MongoDB documents that single-document operations are atomic and that embedding can remove the need for multi-document transactions in many use cases. Use a transaction when the invariant actually spans documents. (high confidence) [source]
- Keep transactions short and size-bounded. Long-running or oversized transactions retain old snapshot state and uncommitted changes, which can pressure WiredTiger's cache, raise latency for other operations, and cause rollback or abort. Avoid large batches in one transaction and abort abandoned work promptly. (high confidence) [source]
- Keep DDL such as index creation or collection renames outside the transaction's critical path when they touch the same namespace. MongoDB documents that pending DDL can wait for an active transaction, while new affected transactions can wait behind the pending DDL and then abort on lock timeout. (high confidence) [source]
Problems, failure modes and limitations
- Make retryable transaction callbacks idempotent and do not perform irreversible external side effects inside them unless those effects use deduplication. A driver's `withTransaction` callback may run multiple times when a transient transaction error causes the whole transaction to be retried, so an email, charge, or webhook in the callback can otherwise happen more than once. (high confidence) [source]
- For integrations that start transactions lazily, avoid sending multiple asynchronous commands on the same session before its first transaction command completes. A Payload issue reports that out-of-order first commands can fail with `NoSuchTransaction` on its tested stack. (low confidence) (verified as of 2026-10-13) [source]
- Do not leave a transaction open while application code waits on a user or an external service. An open transaction pins its snapshot and keeps older document versions in WiredTiger; later writes can grow the retained history, increase cache and eviction pressure, and add latency or conflicts. Commit or abort promptly, and abort transactions that the application abandons or encounters an operation error in. (high confidence) [source]
- Bound transaction work and keep it fast: avoid slow or unindexed queries and unnecessarily large document sets. Long scans extend snapshot lifetime, while large transactions increase cache and conflict exposure. Starting in MongoDB 6.2, the server does not retry a transaction that returns `TransactionTooLargeForCache`, because the cache-capacity problem is likely to make an unchanged retry fail again. Split work only when the business invariant permits partial commits. (high confidence) (verified as of 2026-10-20) [source]
Comparisons and alternatives
- Treat hot-document contention inside a transaction as retry amplification rather than a cheap failure: a `TransientTransactionError` can restart the whole callback and discard prior work. Reduce conflict windows and avoid repeatedly updating a hot document early in a long transaction. (high confidence) [source]
Facts and statements
- Pass the `ClientSession` to every database operation that should participate in `withTransaction`. The helper does not enforce this association, so an operation without the session can run outside the transaction. (high confidence) [source]
Children
- No children recorded.