How do you handle concurrent optimistic updates without older responses overwriting newer data?

[kuldeeprajput-dev]

I have multiple mutations updating the same query cache.

For example, if a user quickly updates the same item twice:

mutation.mutate({ id: 1, status: "pending" })
mutation.mutate({ id: 1, status: "done" })

I update the cache optimistically in onMutate and invalidate the query in onSettled.

The problem is that sometimes the first request finishes after the second one, and the older response/refetch can overwrite the latest state.

What is the recommended way to handle this in TanStack Query?

Should I cancel queries, track mutation versions, avoid invalidating after every mutation, or handle this some other way?

[barry166]

If the same item can be mutated more than once, give the mutation a shared scope.id so those writes run in order.

Keep the normal optimistic-update pattern in onMutate:

await queryClient.cancelQueries({ queryKey: ['item', id] })
const previous = queryClient.getQueryData(['item', id])
queryClient.setQueryData(['item', id], optimistic)

cancelQueries stops a stale refetch from clobbering the optimistic write. If the server returns the updated item, write that response back with setQueryData and only invalidate when you actually need a resync.

[TkDodo]

1. You only invalidate after the last mutation is done by adding a guard:

onSettled: () => {
  if (queryClient.isMutating(filter) === 1) {
    queryClient.invalidateQueries(...)
  }
}

filter should filter for mutations you care about

2. You run those mutations in a queue by setting scope.id on your mutation. All mutations in the same scope are guaranteed run in serial.

[ignaciobockl]

Hi @kuldeeprajput-dev . Combine the two approaches above — they solve different halves.

scope.id serializes same-item writes so “pending” can’t overtake “done”. cancelQueries + snapshot/rollback + single invalidate handles the read side. Either alone still races.

const mutation = useMutation({
mutationFn: updateItem,
scope: { id: item-${id} },
onMutate: async (variables) => {
await queryClient.cancelQueries({ queryKey: ['item', variables.id] });
const previous = queryClient.getQueryData(['item', variables.id]);
queryClient.setQueryData(['item', variables.id], (old) => ({
...old, ...variables, _v: (old?._v ?? 0) + 1,
}));
return { previous, id: variables.id };
},
onError: (_err, variables, context) => {
if (context?.previous) queryClient.setQueryData(['item', variables.id], context.previous);
},
onSuccess: (serverItem, variables) => {
queryClient.setQueryData(['item', variables.id], (old) => {
if (!old || (serverItem._v ?? 0) >= (old._v ?? 0)) return serverItem;
return old;
});
},
onSettled: () => {
if (queryClient.isMutating({ scope: { id: item-${id} } }) === 1) {
queryClient.invalidateQueries({ queryKey: ['item', id] });
}
},
});

Why: scope.id guarantees serial execution per item; cancelQueries stops a stale refetch from clobbering the optimistic write; the _v version (or server updatedAt) makes “older response overwrites newer” structurally impossible; the isMutating guard turns N rapid mutates into 1 invalidate instead of N refetch races; writing the server response via setQueryData avoids a refetch entirely when the server returns the row.

Sources:
https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates
https://tanstack.com/query/latest/docs/framework/react/guides/mutations
https://tanstack.com/query/latest/docs/reference/QueryClient