Features_Request: Timer Diagnostics for Active Queries #9951
Description
Describe the bug
This is a feature request / missing tooling rather than a regression.
Today, timer‑driven behavior in TanStack Query is effectively opaque. When a query or mutation schedules a timer (for staleTime, gcTime, refetchInterval, or retries), there is no public, supported way to inspect which timers are currently active or when they will fire.
This makes debugging unexpected refetches, stale transitions, cache eviction and retry storms difficult. Devtools can show query state, but cannot show the underlying timers that are driving that state, so reproducing timing‑sensitive issues often requires guesswork and manual logging
Your minimal, reproducible example
Minimal repro concept (can be turned into a CodeSandbox / StackBlitz): ts const queryClient = new QueryClient() // Query 1: uses staleTime and gcTime useQuery({ queryKey: ['user', id], queryFn: fetchUser, staleTime: 5_000, gcTime: 60_000, }) // Query 2: uses refetchInterval and retry useQuery({ queryKey: ['notifications'], queryFn: fetchNotifications, staleTime: Infinity, refetchInterval: 10_000, retry: 3, retryDelay: 1_000, }) Repro: trigger these queries, then open Devtools. There is no way to see: which timers are active, which query/mutation they belong to, whether they are intervals vs one‑shots, or how long until each fires. I can provide a public sandbox if needed, but the issue is essentially the absence of any timer diagnostics / inspector.
Steps to reproduce
Create a
QueryClient
and attach Devtools.
Add one or more queries/mutations that use:
staleTime,
custom gcTime,
refetchInterval,
and/or retry with retryDelay.
Trigger a few requests so timers are scheduled (stale timers, GC timers, refetch intervals, retry delays).
Open TanStack Query Devtools and inspect the query/mutation details.
Observed:
There is no view, panel, or API to see which timers are active, when they will next fire, or whether they are intervals.
Debugging issues like “why does this refetch keep happening?” or “when will this query be GC’d?” requires reading internal code or adding manual logging.
Expected behavior
I’d like a small, read‑only diagnostics surface in core (and a corresponding Devtools panel) that exposes a snapshot of active timers.
Roughly:
A diagnostics API on
QueryClient
, e.g.
queryClient.getTimerDiagnostics()
, returning a read‑only array.
Each item would describe:
type: 'stale' | 'gc' | 'refetch' | 'retry'
queryHash (or similar identifier for queries and mutations)
msUntilFire: milliseconds until the next scheduled firing (clamped at 0)
isInterval: true for interval timers (e.g. refetchInterval), false otherwise.
A Devtools “Timers” / “Timer Inspector” view that surfaces this snapshot, filterable by query key / mutation key.
Calls should be cheap, side‑effect free, and safe to use in production. If a user never calls the diagnostics API or opens the Devtools timer panel, existing behavior should remain unchanged.
How often does this bug happen?
Every time
Screenshots or Videos
No response
Platform
OS: Windows 11
Browser: Chrome (latest at time of filing)
Node: 20.x
Package manager: pnpm
Tanstack Query adapter
react-query
TanStack Query version
tanstack/query-core@5.90.12 (and matching tanstack/react-query / Devtools versions in the same major range)
TypeScript version
No response
Additional context
This feature would be especially useful when:
Debugging unexpected refetches driven by refetchInterval or focus/online events.
Understanding when inactive queries and mutations will be garbage‑collected (gcTime).
Inspecting retry behavior in production without adding custom logging.
A small diagnostics API in core + a Devtools “Timer Inspector” would make it much easier to answer “what timers are currently scheduled, and why?” without digging into internal implementation details.