TanStack Query Not Refetching— staleTime, Polling & Invalidation [2026]
Also covers: staleTime · refetchOnWindowFocus · refetchInterval · manual refetch · invalidateQueries after mutation
⚡ The Symptom
// Data never updates after first fetch
// Switching tabs doesn't trigger a refetch
// Mutations complete but query shows stale data✅ Key settings that control refetching
useQuery({
queryKey: ["posts"],
queryFn: fetchPosts,
staleTime: 60_000, // data is fresh for 1 min
refetchOnWindowFocus: true, // refetch when tab regains focus
refetchInterval: false, // no polling by default
})Why TanStack Query Stops Refetching
TanStack Query refetches in the background when certain triggers fire: window focus, component remount, network reconnect, or manual invalidation. These refetches only happen when the data is stale . If staleTime is set very high or Infinity, data is never considered stale and background refetches never trigger.
Understand and Set staleTime Correctly
Data never refetches — staleTime too high// staleTime: 0 (default) — always stale, refetches on every focus/mount
// staleTime: 60_000 — fresh for 1 minute
// staleTime: Infinity — never stale, never background-refetches
// Per-query staleTime
const { data } = useQuery({
queryKey: ["posts"],
queryFn: fetchPosts,
staleTime: 5 * 60 * 1000, // 5 minutes — good for slowly-changing data
})
// Global default staleTime in QueryClient
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 60 * 1000, // 1 minute for all queries by default
},
},
})Use staleTime: Infinity only for truly static data (config, translations). For user data, prices, or anything that changes, use a specific time value so background refetches keep the UI fresh.
Enable refetchOnWindowFocus
Data stays stale after switching tabs// Global — enabled by default, but you may have disabled it
const queryClient = new QueryClient({
defaultOptions: {
queries: {
refetchOnWindowFocus: true, // default — true
refetchOnMount: true, // default — true
refetchOnReconnect: true, // default — true
},
},
})
// Per-query override
const { data } = useQuery({
queryKey: ["live-prices"],
queryFn: fetchPrices,
staleTime: 0, // always stale
refetchOnWindowFocus: true, // refetch when user returns to tab
})
// Set to 'always' to refetch even when data is not stale
const { data } = useQuery({
queryKey: ["notifications"],
queryFn: fetchNotifications,
refetchOnWindowFocus: "always", // always refetch on focus, even if fresh
})Use refetchInterval for Polling
Live data that must update automatically// Poll every 30 seconds
const { data: liveData } = useQuery({
queryKey: ["live-dashboard"],
queryFn: fetchDashboardData,
refetchInterval: 30_000, // poll every 30 seconds
refetchIntervalInBackground: true, // keep polling even in background tab
})
// Conditional polling — stop when data meets a condition
const { data: job } = useQuery({
queryKey: ["job", jobId],
queryFn: () => fetchJob(jobId),
refetchInterval: (query) => {
// Stop polling when job is complete
if (query.state.data?.status === "completed") return false
return 5000 // poll every 5 seconds while running
},
})Manually Trigger a Refetch
Button click / user action triggers fresh fetch"use client"
import { useQuery } from "@tanstack/react-query"
export function DataPanel() {
const { data, isFetching, refetch } = useQuery({
queryKey: ["stats"],
queryFn: fetchStats,
})
return (
<div>
<div className="flex items-center gap-2">
<h2>Statistics</h2>
{isFetching && <span className="text-xs text-gray-400">Refreshing...</span>}
<button
onClick={() => refetch()} // ← triggers an immediate refetch
disabled={isFetching}
>
Refresh
</button>
</div>
<Stats data={data} />
</div>
)
}Invalidate Queries After Mutations
Mutation completes but list shows stale dataimport { useMutation, useQueryClient } from "@tanstack/react-query"
export function CreatePostButton() {
const queryClient = useQueryClient()
const mutation = useMutation({
mutationFn: (newPost: { title: string; content: string }) =>
fetch("/api/posts", {
method: "POST",
body: JSON.stringify(newPost),
}).then(r => r.json()),
onSuccess: () => {
// ✅ Invalidate the posts list — triggers background refetch
queryClient.invalidateQueries({ queryKey: ["posts"] })
// ✅ Invalidate multiple related queries
queryClient.invalidateQueries({ queryKey: ["posts"] })
queryClient.invalidateQueries({ queryKey: ["user-stats"] })
},
onError: (error) => {
console.error("Failed to create post:", error)
},
})
return (
<button
onClick={() => mutation.mutate({ title: "New Post", content: "..." })}
disabled={mutation.isPending}
>
{mutation.isPending ? "Creating..." : "Create Post"}
</button>
)
}Prevention
- Set staleTime based on how frequently your data changes — not staleTime: Infinity for mutable data
- Always call queryClient.invalidateQueries after mutations — TanStack Query cannot know data changed otherwise
- Use isFetching (not isLoading) to show a refresh indicator during background refetches
- Install ReactQueryDevtools to visualise stale/fresh state and trigger times
- Use refetchInterval for live data like prices, notifications, or job status polling
- Never disable refetchOnWindowFocus globally — it's one of TanStack Query's best UX features
Frequently Asked Questions
Why does TanStack Query not refetch when I switch tabs?+−
What is staleTime in TanStack Query?+−
How do I make TanStack Query poll data every 30 seconds?+−
What is the difference between refetch() and invalidateQueries()?+−
Why is TanStack Query not refetching after a mutation?+−
Can TanStack Query refetch in the background without showing a loading state?+−
Need Expert Help?
We Build Data-Driven UIs with TanStack Query
Softplix engineers implement TanStack Query with optimal caching, invalidation, and real-time refresh strategies. Let us help.
Talk to an Engineer