tRPC useQuery returning stale data after mutation: invalidate() vs staleTime diagnosis

Answer

The clearest signal is the query’s isInvalidated flag (or the state.status shown in TanStack Query devtools). If the flag becomes true after the mutation but no network request follows, the problem is not staleTime – invalidation forces a refetch regardless of freshness. If the flag stays false, the invalidate() call did not match the query key (including its input parameters), pointing to a key‑mismatch issue.

Why this works

• Invalidation marks a query as stale and triggers a refetch for every active observer, bypassing staleTime entirely.
• If the query never receives the invalidated flag, the key used by useQuery and the key passed to utils.invalidate() differed (deep equality of inputs is required).
• When the flag is true but you still see cached UI, check whether the query had an active observer at the moment of invalidation; inactive queries are only marked stale and will refetch on next mount, subject to staleTime.

Steps to diagnose and fix

1. Open TanStack Query devtools (or log query.state) and run the mutation.
2. Observe the target query: does isInvalidated become true?
3. If yes, verify that a refetch request appears in the Network tab. If it does not, the query lacked an active observer – ensure the component is mounted when the mutation runs or consider refetching on focus.
4. If the flag stays false, log the exact input object used by useQuery and the argument passed to utils.invalidate(). Compare them with a deep‑equality check (e.g., JSON.stringify or lodash.isEqual) to spot mismatches.
5. To rule out a staleTime issue, temporarily set staleTime: 0 on the useQuery call. If the symptom persists after the mutation, the cause is not staleTime.
6. Once the key matches, place await utils.procedure.invalidate(exactInput) inside the mutation’s onSuccess. Awaiting guarantees the invalidation (and thus the refetch) finishes before any subsequent UI logic runs, preventing races with navigations or follow‑up mutations.
7. If the data must be fresh on every mount or focus, add a short per‑procedure staleTime (e.g., staleTime: 1000) as a safety net, but keep invalidation as the primary mechanism for cross‑component consistency.

Missing diagnostic detail

If you cannot tell whether the query had an active observer when the mutation ran, please confirm: was the component displaying the query mounted at the exact moment the mutation’s onSuccess executed?