Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →If TanStack Query makes an unexpected request, shows old data, or appears to lose a cache entry, the cache may be working as designed: cached data can still be present but already be considered stale. Start by identifying whether the problem is freshness, inactive-cache retention, invalidation, or hydration. Each has a different fix; increasing one cache setting will not solve them all.
First identify what the cache problem looks like
- A request repeats while data is visible: check freshness and the event that triggered a refetch.
- Data vanishes after a component unmounts: check how long inactive queries are retained.
- A successful mutation leaves old data on screen: check which cache entry the mutation updates or invalidates.
- Invalidation seems ineffective: check whether the query is disabled or marked static.
- A request happens after server rendering or hydration: check freshness timing, query keys, and QueryClient instances.
- A persisted cache disappears earlier than expected: compare its persistence maxAge with gcTime.
- Prefetched data is followed by a component fetch: check the freshness settings on both prefetch and useQuery.
The documentation links below are TanStack’s current “latest” React documentation, accessed October 7, 2026. APIs and defaults can vary across major versions, so verify the guidance against the version installed in your project, particularly when using older React Query examples.
![Computer Networking Bible: [3 in 1] The Complete Crash Course to Effectively Design, Implement and Manage Networks. Including Sections on Security, Performance and Scalability](https://m.media-amazon.com/images/I/41H4YJnxKgL._SL160_.jpg)
As an Amazon Associate I earn from qualifying purchases.
Why does TanStack Query refetch data that is already cached?
By default, cached query data is considered stale immediately. Stale does not mean missing: the value can remain in the cache and be displayed while TanStack Query fetches an update. A stale query may refetch when a new observer mounts, the browser window regains focus, or network connectivity returns. Those requests can be expected behavior rather than evidence of a broken cache. See TanStack Query’s Important Defaults.
Set freshness with staleTime
staleTime controls how long data is treated as fresh. Set it to match how quickly that data needs to reflect changes in your application; there is no universally correct duration. It can be configured for a query or through QueryClient defaults. TanStack’s documentation says, “Setting staleTime is the recommended way to avoid excessive refetches.”
#1 Best Overall
The Important Defaults guide gives 2 * 60 * 1000 (two minutes) as an example: it says that setting staleTime to that value prevents refetches for two minutes, or until the query is manually invalidated. This is an illustration, not a recommendation for every query.
Choose Infinity or static deliberately
staleTime: Infinityprevents the query from becoming stale due to elapsed time; manual invalidation can still make it eligible for an update.staleTime: 'static'is stricter: the Important Defaults guide saysinvalidateQuerieshas no effect on a static query. Consider it for data that cannot change while the app is running, such as boot-time feature flags, permissions loaded at login, or static reference tables.
Do not use 'static' simply to silence requests if the data can change and needs to respond to invalidation.
What is the difference between staleTime and gcTime?
They govern separate parts of cache behavior. staleTime determines freshness; gcTime determines how long unused data stays in memory after its query becomes inactive. Raising gcTime can preserve inactive data longer, but it does not make stale data fresh or prevent a stale-driven refetch when the query becomes active again. TanStack documents the browser default for inactive retention as five minutes and the server default as Infinity; these are documented defaults, not measured performance results. See the QueryObserverOptions reference.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsWhy does a mutation succeed but the screen still show old data?
Check that the mutation targets the query key that owns the displayed data. invalidateQueries marks matching queries invalidated and, unless refetching is disabled, refetches eligible matches according to the filters. By default, it refetches active matches; refetchType can change which matches are refetched. Invalidation does not remove the cache entry: data can remain present while marked invalid. Consult the QueryClient and Query references.
If the mutation response contains the complete updated resource, the TanStack Start integration guide notes that setQueryData can write it directly to the corresponding cache entry. Use that when you have the authoritative updated value; invalidate when a refetch is needed to obtain or reconcile the current server state.
Why does invalidateQueries appear to do nothing?
Check whether the query is disabled
A query with enabled: false does not automatically fetch on mount or in the background and ignores invalidateQueries and refetchQueries calls that would normally trigger a refetch. The disabling guide states: “The query will ignore query client invalidateQueries and refetchQueries calls that would normally result in the query refetching.” Check whether the condition controlling enabled is still false. A disabled query can be triggered with its returned refetch method, subject to the documented skipToken limitation. See Disabling/Pausing Queries.
Check for static freshness
If the query uses staleTime: 'static', the Important Defaults guide says invalidation has no effect. If the query should respond to manual invalidation, use a freshness policy that permits it, such as Infinity where appropriate.
Free tools Windows power users keep installed
One-click scans. No signup required.
Check the key, filters, and refetchType
Confirm that the key passed to the invalidation call matches the query you intend to refresh and that filters select it. Also inspect refetchType: invalidating a match and choosing whether to refetch it are related but distinct behaviors.
Best Value
- Used Book in Good Condition
Why does a query fetch again after SSR or hydration?
TanStack Query measures staleness from dataUpdatedAt, using UTC timing. With the default staleTime of zero, data can be stale by the time the page hydrates, so a background request on page load may be expected. If avoiding that extra request suits the data, configure a higher staleTime for the relevant query. The Server Rendering & Hydration guide also documents server-side gcTime as Infinity and warns that setting gcTime: 0 can cause hydration errors if data is garbage-collected before rendering references it.
For repeated reads immediately after hydration in TanStack Start, check whether server and client use matching query keys, whether hydration is configured as intended, and whether the app accidentally creates extra QueryClient instances. The TanStack Query integration guide distinguishes Query data from router-owned loader data: queryClient.invalidateQueries refreshes Query data, while router.invalidate() reloads router-owned loader data and route context. If a mutation changes both, invalidate both owners; if it changes only one, refresh that owner.
Why is persisted cache data discarded?
Compare persistence maxAge with Query cache gcTime. The persistQueryClient guide says gcTime should be the same as or higher than maxAge when a restored cache is meant to remain available for the configured persistence period. The persistence plugin also supports a buster string to intentionally discard cache from an outdated build or application state. Use that mechanism when an old cache should not be restored, rather than treating every cache reset as an unexplained failure.
Why does prefetched data still trigger a component fetch?
Prefetching uses the QueryClient’s default staleTime unless the prefetch call supplies its own value. A per-call staleTime applies to that prefetch operation; it does not automatically set the freshness policy for the later useQuery. If the component should treat the prefetched data as fresh for a matching interval, configure staleTime for the subsequent query too. See Prefetching & Router Integration.
Quick Recap
A compact diagnostic checklist
- Identify the symptom: repeated request, missing inactive data, stale post-mutation display, ignored invalidation, hydration request, or lost persisted data.
- For repeated requests, inspect the query’s staleTime and whether mount, focus, or reconnect made a stale query eligible to refetch.
- For data lost while inactive, inspect gcTime; do not expect it to control freshness.
- For old post-mutation data, verify the query key and invalidation filters, or update the cache with complete mutation data.
- For ineffective invalidation, check
enabled,staleTime: 'static', andrefetchType. - For SSR, hydration, or prefetch, compare freshness settings across server, prefetch, and client queries, and verify keys and QueryClient ownership.
- For persisted state, align gcTime with maxAge if the restored cache should remain available for that period.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
