How to prevent race conditions in Next.js optimistic UI updates

Developers love optimistic UI for its instant feedback, but few test what happens when users go rogue. A single checkbox clicked five times in quick succession revealed a subtle flaw in Next.js 16: the UI stayed visually consistent while the database absorbed conflicting requests. The issue wasn’t with useOptimistic itself, but with unchecked concurrency. Without a guardrail, overlapping mutations can overwrite each other silently, leaving the frontend out of sync with reality.

Why optimistic UI hides subtle bugs

Optimistic updates excel at creating the illusion of speed by applying changes instantly, before the server responds. When a user toggles a task to "completed," the checkbox flips immediately, offering immediate gratification. But this approach assumes that users will interact with the interface at a reasonable pace. Real users don’t always comply.

In the demonstration scenario, a rapid sequence of clicks triggered multiple API requests, each racing to flip the same task’s completion status. The database processed these requests in an unpredictable order, potentially leaving the task in an inconsistent state. Meanwhile, the UI remained oblivious, displaying the last optimistic update it rendered. The result? A mismatch between what the user sees and what actually exists in the database—without a single error message to flag the problem.

The minimal fix: per-row request tracking

The solution mirrors the classic form submission pattern: disable the triggering element until the asynchronous operation completes. Instead of locking the entire task list, apply this logic at the individual row level. Track which task is currently being processed and disable its toggle until the operation settles.

const [pendingId, setPendingId] = useState<string | null>(null);

function handleToggle(id: string) {
  if (pendingId === id) return; // Prevent duplicate requests
  setPendingId(id);
  startTransition(async () => {
    setOptimisticTask(id);
    try {
      await toggleTask(id);
    } finally {
      setPendingId(null);
    }
  });
}

The corresponding checkbox input now checks for pending operations before allowing further interaction:

<input
  type="checkbox"
  checked={task.completed}
  disabled={pendingId === task.id}
  onChange={() => handleToggle(task.id)}
/>

This ensures that subsequent clicks on the same checkbox are ignored until the initial request completes. Beyond preventing race conditions, this approach reduces unnecessary database writes—every aborted click saves a redundant operation that would otherwise compete for resources.

When optimistic updates revert automatically

A common misconception involves handling failed updates. Many examples show developers manually rolling back optimistic changes by flipping the state again in a catch block:

try {
  setOptimisticTask(id);
  await toggleTask(id);
} catch {
  setOptimisticTask(id); // Flip back to original state
}

This pattern works, but it’s often unnecessary. The useOptimistic hook doesn’t introduce a separate state tree. Instead, it overlays temporary values on top of the existing state for the duration of the transition. Once the transition completes—whether successfully or not—React discards the overlay and renders from the authoritative state. If the server-side operation fails and the underlying data remains unchanged, the UI snaps back automatically without any additional intervention.

The only exception occurs when the optimistic update introduces a new entity entirely, such as adding a comment with a placeholder ID before the database assigns a permanent one. In this case, there’s no prior server state to revert to. A failed insert doesn’t merely flip a flag; it removes an entity that only existed on the client. Here, manual cleanup in the catch block is required.

Clearing stale data: choosing the right cache invalidation strategy

After successfully toggling a task, the next challenge is ensuring that subsequent page loads or component renders reflect the updated state. Next.js 16 offers three distinct methods for cache invalidation, each with different performance implications.

• revalidatePath targets a specific route, clearing its cache while leaving others untouched.
• revalidateTag invalidates all cache entries sharing a particular tag, using a stale-while-revalidate approach that allows immediate user interaction while background updates occur.
• updateTag—available exclusively through Server Actions—immediately expires a tag, forcing the current page to fetch fresh data without delay.

For an interactive element like a checkbox, updateTag provides the best user experience. The page the user is actively viewing refreshes instantly, eliminating any delay in seeing their changes. For secondary UI elements, such as a task count displayed in a sidebar, revalidateTag offers a more conservative approach. It allows the change to propagate without holding up unrelated parts of the application.

A critical detail for developers on recent Next.js 16 versions: revalidateTag now requires a second argument to specify the revalidation behavior. The pattern has evolved from:

revalidateTag("tasks"); // Deprecated

to:

revalidateTag("tasks", "max"); // Recommended

Omitting the second argument triggers a TypeScript error, ensuring developers adopt the updated syntax.

Handling failed fetches with error boundaries

When asynchronous operations fail due to network issues or server errors, developers often assume the error handling logic remains unchanged by the introduction of transitions. Next.js documentation confirms that errors thrown within startTransition still propagate to the nearest error.tsx boundary.

However, a less documented feature introduced in Next.js 16.2 changes how recovery works. The error.tsx component now receives two distinct recovery props: reset and unstable_retry. These are not interchangeable.

• reset clears the error and re-renders the same children without refetching data. This approach is useful when the error stems from rendering logic rather than data fetching, but it fails to address stale data issues.
• unstable_retry initiates a fresh fetch and re-renders the segment with updated data, effectively resolving failures caused by transient network problems or server-side issues.

export default function TaskListError({
  error,
  unstable_retry,
}: {
  error: Error & { digest?: string };
  unstable_retry: () => void;
}) {
  return (
    <div role="alert">
      <p>Something went wrong loading your tasks.</p>
      <button onClick={unstable_retry}>Retry</button>
    </div>
  );
}

Choosing the wrong recovery method can leave users staring at stale or broken screens, making unstable_retry the appropriate choice for data-fetching errors.

Building resilient UI with intentional concurrency controls

Optimistic UI remains a powerful tool for creating responsive applications, but its benefits come with the responsibility of managing edge cases. By implementing per-row request tracking, understanding automatic revert behaviors, selecting appropriate cache invalidation strategies, and configuring error boundaries correctly, developers can build interfaces that feel fast without compromising data integrity. The next time a user clicks a checkbox five times in quick succession, their actions will result in a single, predictable database update—and the UI will stay perfectly in sync.