What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
staleTime controls how long query data is considered fresh; gcTime controls how long unused query data remains in the cache before removal. Stale data is not deleted: it can remain available while TanStack Query refetches it at configured triggers. Conversely, an inactive query can be garbage-collected even if its last freshness window was long.
What is the difference between staleTime and gcTime?
| Question | staleTime |
gcTime |
|---|---|---|
| What it controls | How long data is considered fresh | How long inactive query data is retained before garbage collection |
| Does it remove cached data? | No. Expiration makes the data stale, not deleted. | Yes. The cache entry is removed when the query is inactive and its retention timer expires. |
| What a shorter value changes | When stale-triggered refetches can occur | How soon inactive data can be removed |
| Current documented default | 0, so data is stale immediately unless configured otherwise |
Five minutes in the browser; Infinity during SSR |
TanStack Query’s current React documentation describes these as separate parts of the query lifecycle. See Important Defaults, the QueryOptions reference, and Server Rendering & Hydration (rolling documentation reviewed October 7, 2026).
As an Amazon Associate I earn from qualifying purchases.
Does stale mean deleted?
No. A query becomes stale when its freshness window ends, but its cached result can still be returned. Staleness makes the query eligible for background refetching at configured triggers; it does not erase the result. The TanStack defaults guide says a query with a staleTime remains fresh until that time elapses.
Free tools Windows power users keep installed
One-click scans. No signup required.
For example, TanStack’s guide shows a two-minute staleTime using 2 * 60 * 1000. That is a configuration example, not a universal recommendation. During the window, data is treated as fresh and does not undergo a staleness-triggered refetch, unless it is manually invalidated. Choose a value based on how quickly the data changes and how acceptable it is for users to see cached results.
#1 Best Overall
When does gcTime remove data?
gcTime matters after a query has no active observers and becomes inactive. In the browser, the current docs specify a default of five minutes (5 * 60 * 1000). If the query remains inactive until that retention timer expires, TanStack Query removes its cache entry. A later need for that query requires fetching it again.
The timer does not begin deleting a query merely because staleTime elapsed. An active query can be stale while still available in the cache. If different observers or options specify different gcTime values, the longest value is used. The API reference also notes that ordinary setTimeout use has a timer limit of about 24 days; very long retention settings therefore have a practical limit. See the QueryOptions reference.
Why is my query refetching?
Stale queries can be refetched in the background when a new query instance mounts, the window is refocused, or network connectivity returns. These are refetch triggers for stale data; gcTime does not schedule them. A separate refetchInterval controls polling, so a long staleTime does not by itself disable interval-based refetching. These behaviors are described in TanStack’s Important Defaults.
If repeated requests are unexpected, distinguish among an expired freshness window, manual invalidation, those automatic triggers, and a configured polling interval. Adjust the option that corresponds to the behavior you intend to change: freshness for stale-triggered refetch eligibility, retention for inactive cache removal.
How do Infinity and static differ?
staleTime: Infinity
Data does not become stale just because time passes, but manual invalidation can still make it stale. This is useful when elapsed time alone should not mark data out of date, while explicit invalidation should still work.
staleTime: 'static'
'static' is stricter: manual invalidation does not affect that query’s staleness, and refetch-on-mount, refetch-on-focus, or refetch-on-reconnect settings set to "always" are blocked. TanStack positions it for data that cannot change during the app session. Use it only when that stronger behavior matches the data; it is not interchangeable with Infinity. See Important Defaults.
What should SSR applications account for?
TanStack documents gcTime as Infinity by default during server-side rendering, rather than the browser’s five-minute default. Server applications should account for the lifetime of each query client and how its cache is cleaned up. The SSR guide warns that setting gcTime to zero can cause hydration errors; it suggests allowing time for hydration or clearing the query client after the request is handled and dehydrated state is sent. See Server Rendering & Hydration.
Why might prefetch and useQuery behave differently?
A staleTime supplied only to a prefetch operation applies to that prefetch; it does not automatically give the corresponding useQuery the same freshness window. If the query should use the same window after it is mounted, set staleTime for useQuery as well. TanStack documents this in Prefetching & Router Integration.
Best Value
What if the code uses cacheTime?
gcTime is the current option name. Older React Query code may use cacheTime, the former name for the corresponding setting. Check the installed @tanstack/react-query version and use documentation for that version rather than assuming current option names and behavior apply unchanged. TanStack explains the rename in its v3-to-v4 migration guide.
Quick Recap
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.
