faunadb 'transaction aborted due to timeout' on contended documents: how to fix

TL;DR

Do not just raise the timeout; fix the contention. Fauna runs transactions under strict serializability with a time budget, and when many transactions fight over the same documents, the retries burn the budget and the transaction aborts. Find the hot documents, split them up (sharded counters are the classic fix), shrink each transaction, and stop piling read-modify-write cycles onto one document.

{"errors": [{"code": "transaction_timeout", "description": "transaction aborted due to timeout"}]}

Steps

1. Identify the contended documents. Look at which documents appear in the failing transactions; there is usually one counter, aggregate, or "current state" document shared by all of them. Expected: one or two documents show up in nearly every aborted transaction.

2. Shard the hot document. Replace a single counter document with N counter documents (picked by hash of the writer or randomly) and sum them on read. Expected: write contention drops roughly by N, and aborts fall with it.

3. Shrink the transaction. Do fewer reads and writes per transaction, and avoid touching the hot document unless the logic truly needs it. Expected: fewer retries per transaction, so fewer transactions run out of budget.

4. Stop the read-modify-write pileup. If many clients concurrently read a doc, increment, and write it back, serialize those updates through a queue or batch them instead. Expected: aborts stop under load because writers no longer invalidate each other in a loop.

5. Only then, if a single transaction is legitimately large and uncontended, raise the transaction timeout within your account limits. Expected: large-but-quiet transactions succeed. Contended ones still need the remodel above; a bigger budget just delays the same abort.

Use this when

• Fauna aborts transactions with a timeout error under concurrent load.
• The same one or two documents appear in most failing transactions.
• Single-threaded tests pass but load tests abort.
• You have counter, aggregate, or singleton state documents with many writers.

Not for this skill when

• Transactions time out without contention, for example one huge transaction doing thousands of reads. That is a size problem; split the work.
• The error is a different Fauna code (permission, validation, not found). Those need their own fixes.
• Aborts happen at low concurrency. Check for an application retry loop re-running a doomed transaction.

Variant phrasings

• fauna transaction_timeout contended document
• faunadb transaction aborted timeout concurrent writes
• fauna sharded counter contention
• fauna strict serializability retry timeout
• faunadb hot document many writers abort

Why it happens

Fauna gives every transaction strict serializability: concurrent transactions that touch the same documents conflict, and the loser retries. Each retry costs time against the transaction's budget. When dozens of writers hammer one document, they invalidate each other faster than any of them can commit, the budget runs out, and Fauna aborts with a timeout. The timeout is the symptom; the single hot document is the disease.

Edge cases

• Sharded counters make writes cheap but reads do N document fetches. For very hot counters that is still a win; for lukewarm ones it may not be worth it.
• Summing on read must handle missing shards (a shard with no writes yet simply contributes zero).
• Raising the timeout on a contended workload increases the thundering herd: longer-running losers hold resources longer. Fix contention first.
• Time-based partitioning (one aggregate doc per hour instead of one global doc) is often simpler than hash sharding when the contention follows the clock.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_aUP--uWbrvIUXYZD3EYoyQ