Invalidation & cache writes

After a write, the cache holds data the server no longer agrees with. TanStack Query v5 gives you five QueryClient methods for that moment, and they are not interchangeable. Ask two questions: do I already have the new data? and is anyone looking at the old data?

The everyday pair is the first two:

// We created a todo; we don't know where it lands in each sorted, filtered list.
await queryClient.invalidateQueries({ queryKey: todoKeys.lists() });

// We renamed todo 5 and the server sent back the updated todo.
queryClient.setQueryData(todoKeys.detail(5), updatedTodo);

Invalidation is the default answer. It marks every matching entry stale — overriding staleTime — and refetches the matching queries that components are using right now, in the background, with their data still on screen. An entry nobody is using is only marked; it refetches when a component next asks for it. That's why "invalidate the whole family" is cheap: you pay for what's visible.

setQueryData is the shortcut when you hold the truth. It writes synchronously, makes no request, and every component reading that key re-renders with the new value. It counts as a fresh fetch, so staleTime starts again from now.

The other three are specialist tools. refetchQueries re-downloads inactive entries too (and doesn't mark anything stale). resetQueries throws data away first, so the user sees a loading state. And removeQueries deletes entries without telling mounted components — the screen keeps the old data until something re-renders it, then shows a hard load.

A rename endpoint returns the full updated todo. The detail view and every cached list show that todo. Refetching all of them would work, but the response already is the new data. Here is the cache update in full:

function applyRenamedTodo(queryClient: QueryClient, saved: Todo) {
  // 1. The detail: we hold its exact new value.
  queryClient.setQueryData(todoKeys.detail(saved.id), saved);

  // 2. Every cached list: patch the one row, immutably.
  queryClient.setQueriesData<Todo[]>({ queryKey: todoKeys.lists() }, (old) =>
    old?.map((todo) => (todo.id === saved.id ? { ...todo, title: saved.title } : todo)),
  );

  // 3. Lists sorted by title on the server: the row may have moved. Let the server decide.
  void queryClient.invalidateQueries({ queryKey: todoKeys.lists() });
}

Step 1 — setQueryData for the one entry you can name. It writes synchronously and makes no request; every component showing that detail re-renders with the new value. If no entry exists for the key yet, one is created — handy for priming a detail page before the user opens it.

Step 2 — setQueriesData for a family. It takes filters instead of a key and runs the updater on every existing match (it never creates entries). Two details in the updater matter:

• old can be undefined, for an entry that exists but has no data yet. Returning undefined leaves that entry untouched, which is why old?.map(...) is safe.
• Return a new array with a new object. The docs are blunt: don't mutate cached data in place. Here is what happens if you do:

queryClient.setQueryData<Todo[]>(todoKeys.list(filters), (old) => {
  old!.find((t) => t.id === saved.id)!.title = saved.title; // ❌ same array, same object
  return old;
});

Run against v5.104 with a list on screen: the cache holds the new title, but the component doesn't re-render. useQuery re-renders a component only when a result field it reads has changed ("tracked properties"), and data is the very same array as before — so the screen keeps the old title until something else re-renders it. An immutable update hands the cache a new reference, and that is what it notices.

Step 3 — invalidate what you can't compute. If the server sorts lists by title, or the rename changes which filter a todo belongs to, a client-side patch could put the row in the wrong place. Invalidate the lists and keep step 2 only as an instant preview (or drop it). Note the filter: todoKeys.lists(), not todoKeys.all — the broader one would also refetch the detail you wrote in step 1.

The rule of thumb:

Each of these was run against TanStack Query v5.104 with a component on screen.

removeQueries on a query someone is showing

function logout() {
  queryClient.removeQueries(); // ❌ the dashboard is still mounted
  navigate("/login");
}

The entries are deleted, but mounted components aren't notified: the dashboard keeps rendering the old user's data. The moment anything re-renders it, its useQuery finds no entry, creates a new one, and shows a hard loading state while it fetches — possibly as the logged-out user. (v5 removed useQuery's own remove() for exactly this reason: removing an active query "will just trigger a hard loading state with the next re-render.") Leave the screen first, then clear the cache (queryClient.clear() empties it entirely), or invalidate what should refresh.

resetQueries as a "Refresh" button

resetQueries returns matches to their initial state before refetching the active ones. Without initialData, the initial state is pending with no data, so the table vanishes behind a spinner. A refresh that keeps the table on screen is invalidateQueries (or refetch() from the hook).

What await invalidateQueries(...) waits for

It resolves when the active queries it refetched have settled (inactive ones are only marked, so there's nothing to wait for). Two consequences:

• It resolves even if the refetch failed. Failures are swallowed unless you pass { throwOnError: true } as the second argument; after a failed refetch, data is still the old value and status is error. "Awaited invalidation" does not mean "fresh data".
• Returning it from a mutation's onSuccess keeps the mutation pending until the refetch is done, so a "Saving…" state lasts until the list really shows the change. The mutations unit builds on this.

Invalidating while a fetch is already running

A refetch started before your write may return pre-write data. By default (cancelRefetch: true) an invalidation cancels an in-flight refetch of a query that already has data and starts a new one, so what lands was requested after the write. A first load (no data yet) that's in flight is joined rather than restarted.

Queries that ignore you

• Disabled queries (enabled: false) aren't refetched by invalidateQueries or refetchQueries, though they're still marked stale.
• staleTime: "static" queries ignore invalidation entirely; Infinity ones don't.
• invalidateQueries() with no filter marks everything stale and refetches every active query in the app. It's a sledgehammer; aim it with a key.