1# OCC Conflict Resolution
2 
3Use these rules when insights, logs, or dashboard health show OCC (Optimistic
4Concurrency Control) conflicts, mutation retries, or write contention on hot
5tables.
6 
7## Core Principle
8 
9Convex uses optimistic concurrency control. When two transactions read or write
10overlapping data, one succeeds and the other retries automatically. High
11contention means wasted work and increased latency.
12 
13## Symptoms
14 
15- OCC conflict errors in deployment logs or health page
16- Mutations retrying multiple times before succeeding
17- User-visible latency spikes on write-heavy pages
18- `npx convex insights --details` showing high conflict rates
19 
20## Common Causes
21 
22### Hot documents
23 
24Multiple mutations writing to the same document concurrently. Classic examples:
25a global counter, a shared settings row, or a "last updated" timestamp on a
26parent record.
27 
28### Broad read sets causing false conflicts
29 
30A query that scans a large table range creates a broad read set. If any write
31touches that range, the query's transaction conflicts even if the specific
32document the query cared about was not modified.
33 
34### Fan-out from triggers or cascading writes
35 
36A single user action triggers multiple mutations that all touch related
37documents. Each mutation competes with the others.
38 
39Database triggers (e.g. from `convex-helpers`) run inside the same transaction
40as the mutation that caused them. If a trigger does heavy work, reads extra
41tables, or writes to many documents, it extends the transaction's read/write set
42and increases the window for conflicts. Keep trigger logic minimal, or move
43expensive derived work to a scheduled function.
44 
45### Write-then-read chains
46 
47A mutation writes a document, then a reactive query re-reads it, then another
48mutation writes it again. Under load, these chains stack up.
49 
50## Fix Order
51 
52### 1. Reduce read set size
53 
54Narrower reads mean fewer false conflicts.
55 
56```ts
57// Bad: broad scan creates a wide conflict surface
58const allTasks = await ctx.db.query("tasks").collect();
59const mine = allTasks.filter((t) => t.ownerId === userId);
60```
61 
62```ts
63// Good: indexed query touches only relevant documents
64const mine = await ctx.db
65  .query("tasks")
66  .withIndex("by_owner", (q) => q.eq("ownerId", userId))
67  .collect();
68```
69 
70### 2. Split hot documents
71 
72When many writers target the same document, split the contention point.
73 
74```ts
75// Bad: every vote increments the same counter document
76const counter = await ctx.db.get(pollCounterId);
77await ctx.db.patch(pollCounterId, { count: counter!.count + 1 });
78```
79 
80```ts
81// Good: shard the counter across multiple documents, aggregate on read
82const shardIndex = Math.floor(Math.random() * SHARD_COUNT);
83const shardId = shardIds[shardIndex];
84const shard = await ctx.db.get(shardId);
85await ctx.db.patch(shardId, { count: shard!.count + 1 });
86```
87 
88Aggregate the shards in a query or scheduled job when you need the total.
89 
90### 3. Move non-critical work to scheduled functions
91 
92If a mutation does primary work plus secondary bookkeeping (analytics,
93non-critical notifications, cache warming), the bookkeeping extends the
94transaction's lifetime and read/write set.
95 
96```ts
97// Bad: canonical write and derived work happen in the same transaction
98await ctx.db.patch(userId, { name: args.name });
99await ctx.db.insert("userUpdateAnalytics", {
100  userId,
101  kind: "name_changed",
102  name: args.name,
103});
104```
105 
106```ts
107// Good: keep the primary write small, defer the analytics work
108await ctx.db.patch(userId, { name: args.name });
109await ctx.scheduler.runAfter(0, internal.users.recordNameChangeAnalytics, {
110  userId,
111  name: args.name,
112});
113```
114 
115### 4. Combine competing writes
116 
117If two mutations must update the same document atomically, consider whether they
118can be combined into a single mutation call from the client, reducing round
119trips and conflict windows.
120 
121Do not introduce artificial locks or queues unless the above steps have been
122tried first.
123 
124## Related: Invalidation Scope
125 
126Splitting hot documents also reduces subscription invalidation, not just OCC
127contention. If a document is written frequently and read by many queries, those
128queries re-run on every write even when the fields they care about have not
129changed. See `subscription-cost.md` section 4 ("Isolate frequently-updated
130fields") for that pattern.
131 
132## Verification
133 
1341. OCC conflict rate has dropped in insights or dashboard
1352. Mutation latency is lower and more consistent
1363. No data correctness regressions from splitting or scheduling changes
1374. Sibling writers to the same hot documents were fixed consistently
138