TanStack Query staleTime vs gcTime Explained

staleTime and gcTime control two different parts of the TanStack Query cache. staleTime decides when data is old enough to refetch, while gcTime decides how long unused data stays in memory. Confusing the two leads to extra requests or stale screens, so this guide separates them clearly.

The difference in one sentence

staleTime answers when data is old. gcTime answers when unused data is deleted. A query can be stale but still cached, or fresh and about to be garbage collected, so the two values are independent.

The table shows the split. staleTime is about freshness, and gcTime is about memory. Neither option controls the other, so tuning one leaves the other alone. When a refetch keeps happening or a cache keeps disappearing, check the matching timer first.

staleTime controls refetching

staleTime is the window in which TanStack Query treats data as fresh and skips refetching. Think of it as a freshness timestamp attached to each cached result. The default is zero, so every result is stale immediately and refetches on mount, window focus, and reconnect.

App.jsx

useQuery({
  queryKey: ["posts"],
  queryFn: fetchPosts,
  staleTime: 5 * 60 * 1000,
});

Setting staleTime to five minutes means the data is treated as fresh for five minutes after it arrives. During that window, the refetch triggers do nothing.

After it, the data is stale, and the next trigger refetches it in the background. A longer staleTime is the main way to reduce requests for data that changes rarely. For user-generated content that changes often, keep staleTime short so edits show up quickly.

gcTime controls cache lifetime

gcTime is how long unused data stays in memory after the last component stops using it. The default is five minutes, and in TanStack Query v5 the option is named gcTime. Older v4 guides call it cacheTime, so rename that option when reading older code.

App.jsx

useQuery({
  queryKey: ["posts"],
  queryFn: fetchPosts,
  gcTime: 10 * 60 * 1000,
});

While a component uses a query, gcTime does nothing. Once the last component unmounts, a timer starts, and the cache entry is removed when it ends.

Removing it frees memory, and the next mount has to fetch again. Set gcTime to Infinity to keep data forever, or lower it to reduce memory on large apps.

How they interact

A typical request follows both timers at once. While the data is fresh, staleTime protects it from refetching, and while a component uses it, gcTime never runs. You rarely set both at once; you usually tune whichever timer is causing the problem.

• Fresh data on screen: no refetch and no garbage collection.
• Stale data on screen: a background refetch, but still no garbage collection.
• Component unmounts: the gcTime timer starts while staleTime keeps counting.
• gcTime ends: the entry is deleted, so the next mount fetches from scratch.

The key idea is that staleTime is about data being current, while gcTime is about data still being available. Both defaults are safe, but teams commonly raise staleTime first and leave gcTime alone.

A plain Effect fetch has neither timer, which is why how to fetch API data in React recommends a data library for larger apps. The cache and key behavior behind both options is in useQuery explained, and the shared client they run on is set up in how to set up TanStack Query in React.