convex-write-conflicts

Preventing Write Conflicts in Convex with React

Write conflicts occur when two functions running in parallel make conflicting changes to the same table or document. This rule provides patterns to avoid these conflicts.

Understanding Write Conflicts

According to Convex documentation, write conflicts happen when:

1. Multiple mutations update the same document concurrently
2. A mutation reads data that changes during execution
3. Mutations are called more rapidly than Convex can execute them

Convex uses optimistic concurrency control and will retry mutations automatically, but will eventually fail permanently if conflicts persist.

Backend Protection: Idempotent Mutations

Always Make Mutations Idempotent

Mutations should be safe to call multiple times with the same result.

Good Pattern:

export const completeTask = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    const task = await ctx.db.get(args.taskId);

    // Early return if document doesn't exist
    if (!task) {
      return null;
    }

    // Early return if already in desired state
    if (task.status === "completed") {
      return null;
    }

    // Only update if state change is needed
    await ctx.db.patch(args.taskId, {
      status: "completed",
      completedAt: Date.now(),
    });

    return null;
  },
});

Bad Pattern:

// This will cause conflicts if called multiple times rapidly
export const completeTask = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    const task = await ctx.db.get(args.taskId);
    // No check if already completed
    await ctx.db.patch(args.taskId, {
      status: "completed",
      completedAt: Date.now(),
    });
    return null;
  },
});

Avoid Unnecessary Reads - Patch Directly

When you only need to update fields, patch directly without reading first. Database operations throw if the document doesn't exist.