A transaction callback can run again
A transaction groups database reads and writes under the service's transaction contract. When concurrent work conflicts, client libraries can retry transaction execution. The callback therefore needs to be safe to evaluate more than once, even if the business wants only one final operation.
Sending an email, charging a payment or calling another service inside that callback introduces an external effect that the database cannot automatically roll back. Contention diagnosis and side-effect ownership belong in the same review, because retrying the database work can repeat the external action.
Setup: record the client and concurrency contract
Identify the Firestore edition, client library, runtime and transaction pattern. Review current documentation for the selected client type and concurrency mode. Mobile or web client behavior and server client behavior should not be assumed identical simply because they use the same database.
Map the documents read and written by the transaction and estimate how often independent requests touch the same document. Include shared counters, tenant metadata and globally updated configuration. A short transaction can still encounter heavy contention if many writers repeatedly target one common document.
Diagnose a conflicting workload
- Capture the precise failure code, timing and application attempt identity. Compare retry counts and elapsed duration with database and application logs, excluding sensitive document contents from broad incident records.
- Identify the shared documents and request patterns involved. Distinguish a true high-contention record from a general backend latency problem or an unrelated client timeout.
- Inspect callback work for external calls, mutable process state and long computation. Determine which actions can run repeatedly and which occur only after a successful committed result.
- Review supported retry limits and deadlines for the actual client. Increasing retries without reducing contention can consume more capacity and prolong user-visible delay.
Illustrative incident: a retried callback sends two notifications
In this illustrative scenario, two requests update the same business record. One transaction callback sends a notification before its database attempt commits. A conflict causes the client to retry, and the notification action runs again even though only one final state transition is intended.
The team moves the effect into a durable post-commit workflow keyed to the business operation and reduces the shared document's write pressure. It tests concurrent requests and repeated delivery separately. The example explains a design boundary and does not report a real duplicate customer notification.
Diagnostic table
| Observation | Evidence | Boundary |
|---|---|---|
| Repeated contention failures | Conflicting document identities | Shared write hotspot |
| Callback executes multiple times | Attempt-level application trace | Transaction retry behavior |
| Database state is correct, external action repeats | Business operation and effect IDs | Side effect outside transaction |
| More retries increase latency | Retry count and total deadline | Retry capacity budget |
Correction and verification
Reduce unnecessary shared writes and shorten the transaction's database-dependent work. Where the business model allows it, redesign high-contention records or use a documented aggregation pattern. Preserve the invariants the transaction was intended to enforce rather than removing consistency checks merely to suppress an error.
Run a controlled concurrent workload against a test dataset and verify final document state, retry behavior and external-effect count. Include failed attempts, deadline exhaustion and an application retry after an ambiguous client outcome. Idempotency keys need durable ownership that spans process restarts.
SOP and monitoring
Track contention failures, retries, transaction latency and business completion independently. Record client versions and transaction invariants in the runbook. The SOP should identify the owner who can approve a data-model change and the evidence needed to show that a retry fix preserves both database correctness and the intended once-per-business-operation effect.
See Clouvenix database administration for implementation and operational handover.
Technical reference
Official reference 1. Documentation checked 20 October 2026; confirm behavior for your deployed edition and version.