Using TanStack Query?

Queries refetching when they shouldn't? We sort it out.

TanStack Query starts as a few hooks and quietly becomes the data layer of the entire app. When invalidation goes wrong, stale time is left at the default, or server components hand hydration a snapshot the client does not agree with, the symptoms are rarely where the bug lives. We trace it through the devtools, the query keys and the server boundary until the network panel matches what the user actually needs.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

query-client.log

still refetching

What it is

TanStack Query at a glance

TanStack Query, long known as React Query, is a client-side data-fetching and caching library for React, Vue, Svelte, Solid and Angular. It handles caching, background refetching, deduplication, pagination, mutations and devtools without forcing a particular transport underneath, which means it works happily over REST, GraphQL or a plain fetch call.

It has become the default answer for anything more complex than a single useEffect fetch. The core idea is that server state is not the same as client state: it goes stale, needs to be revalidated, and should be shared between components without a store. By 2026 it is paired with server components, streaming SSR and framework-level caches in ways the original React Query authors never imagined.

Type
Data fetching and caching library
First released
2020 as React Query v1
License
MIT, permissive
Maintained by
Tanner Linsley and the TanStack contributors
Typically used for
Caching server data in React, Vue, Svelte and Solid apps, replacing hand-rolled fetch state, pairing with SSR frameworks

The honest version

TanStack Query pros and cons

No technology is all upside. This is where TanStack Query earns its place and where it tends to cause trouble.

Where TanStack Query is strong

  • Server state has a proper homeStale time, cache time, retries, deduplication and background refetching all sit in one place rather than being re-implemented per feature by whoever picks up the ticket.
  • The devtools are genuinely usefulInspecting active queries, their state and the last fetched data in the browser turns a vague 'why is this refetching' question into something you can answer in a minute.
  • Mutation and invalidation story is coherentMutations expose onSuccess, onError and onSettled, and invalidateQueries with a key pattern makes dependent data refresh without manual plumbing.
  • Framework-agnostic coreThe same mental model works in React, Vue, Svelte and Solid, so moving between frameworks or sharing engineers across them costs less than it used to.
  • Good SSR integration with Next.js and RemixHydration helpers, prefetchQuery and dehydrate let you render with real data on the server and hand the client a working cache rather than a blank one.
  • Suspense support when you want ituseSuspenseQuery lets you lean on React's Suspense boundaries for loading and error states instead of writing if-isLoading ladders in every component.

Where TanStack Query bites

  • The defaults are aggressivestaleTime is 0, refetchOnWindowFocus is on, and refetchOnMount is true. A busy app can fire hundreds of requests a minute if nobody adjusts those knobs to the actual freshness the data needs.
  • Query keys are a convention, not a typeTypos in a key, keys that accidentally collide, or keys that change identity on every render all break caching in ways the compiler cannot catch. Teams end up building their own key factory.
  • Hydration mismatches in Next.js app routerServer components prerender data, the client hydrates with another QueryClient, and if the dehydrated state is not threaded through correctly you get a mismatch that only shows up on the first paint.
  • Optimistic updates are easy to get wrongRolling back a mutation, replaying it after a retry and avoiding a stale server response clobbering the optimistic one all require care. The happy path is deceptively short.
  • The bundle size adds upThe core is lean but devtools, persister, sync-storage and the query broadcast plugins add weight. Not huge, but real on a landing page that wanted a few kilobytes.
  • Overused for things that are not server stateForm state, modal open/close, and local UI toggles end up in queries because the hook is familiar, which fights the tool and makes rendering harder to reason about.

Sound familiar?

Common TanStack Query problems we fix

The TanStack Query problems that bring people to us, and what you have once each one is fixed.

refetchOnWindowFocus triggered: 14 queries refetched

The app hammers the API on every tab switch

Default staleTime of zero combined with refetchOnWindowFocus means every return to the tab fires every active query, which is fine in dev and ruinous on a real backend.

Refetches tuned to real freshness

Hydration failed because the initial UI does not match

Next.js hydration mismatches on every page

A server render that fetched with one QueryClient and a client that boots with another, no dehydrated state in between, so the first client render disagrees with the HTML and React throws it away.

SSR cache handed through cleanly

No queryFn was passed as an option

Mutation finishes but the UI never updates

A mutation that invalidated the wrong key, or a key that changed identity between renders, so the query it was supposed to refresh never saw the invalidation and kept serving stale data.

Invalidation matches the real keys

Query data cannot be undefined

Queries throw because the fetch returned nothing

A queryFn that returned undefined on a 404 instead of throwing, which TanStack Query treats as a logic error rather than a missing resource. The component downstream sees a broken cache entry.

Missing and error cases handled explicitly

Missing queryClient: No QueryClient set

Component tree never sees a provider

A test harness, a Storybook story or a server component that rendered without QueryClientProvider in the tree. Easy to miss until exactly one route breaks.

Provider wired in every entry point

Infinite query: getNextPageParam returned undefined

Infinite scroll stops after the first page

A getNextPageParam that reads a field from the wrong place in the response, or an API that signals end of list differently than the hook expected.

Pagination carries to the final page

staleTime: 0 (default), refetchOnMount: true

Shared components fire the same request five times

Five components each call the same useQuery with the same key but mount at slightly different times with a stale time of zero, and the dedupe window is too short to collapse them.

Shared data cached once

Mutation failed: no mutationFn provided

Optimistic update rolls back incorrectly

An onError handler that restores the wrong snapshot, or a mutation that races with a refetch and ends up persisting the stale version instead of the optimistic one.

Optimistic path safe under retries

What we do

TanStack Query help, from refetch tuning to SSR

Call us for one runaway query, or hand us the whole data layer.

Rescue
APIs being hammered, hydration throwing on every page, or mutations that never update the list. We stabilize the behavior and write down why.
Cache tuning
Stale time, cache time, refetch triggers and retry policy set per query family against real freshness needs rather than the library defaults.
SSR and app router integration
Dehydrated state threaded from server to client, prefetching that actually helps, and hydration boundaries that agree on the initial render.
Mutation and invalidation design
A key factory, typed invalidation patterns, optimistic updates that roll back cleanly and mutations that compose with Suspense without surprise.
Audits and reviews
A sweep through an existing codebase to find query keys that collide, hooks that leak, and components misusing queries for local state.
Managed Tech
A standing review of query metrics, SSR hydration health and devtools-driven regressions, plus a line to call when a framework upgrade changes the cache behavior.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running TanStack Query alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

TanStack Query questions

Something else? Call+1 737 727 7327

Why is TanStack Query firing so many requests?

The defaults are optimistic: staleTime is zero, refetchOnWindowFocus is on, and refetchOnMount is on. Most apps want a staleTime measured in seconds or minutes for data that does not change on every keystroke, and refetchOnWindowFocus turned off for things that do not need per-tab freshness. We tune per query rather than globally.

How do we fix hydration mismatches with Next.js app router?

Use a single QueryClient per request on the server, prefetch the queries that render in the HTML, dehydrate that state and pass it into HydrationBoundary on the client. The mismatch disappears once both halves agree on the initial snapshot.

Should we use TanStack Query or server actions in Next.js 15?

They serve different jobs. Server actions are great for writes that redirect or revalidate a route; TanStack Query shines when the client needs its own cache, optimistic updates, infinite scroll or background refetching. Most apps end up using both and letting each do what it is best at.

How do we structure query keys without them colliding?

Use a key factory that produces arrays like users.detail(id) and users.list(filters), import it everywhere, and never build keys by hand in a component. It makes invalidation predictable and gives TypeScript something to help with.

Why does our mutation succeed but the list never updates?

The mutation returned a 200 but the invalidateQueries call used a key that does not match the one the list is subscribed to. The fix is usually either moving to the same key factory or widening the invalidation to a prefix, depending on how cheap the refetch is.

How much does TanStack Query help cost?

The first conversation is free. Describe the hooks that are misbehaving, the framework around them, and we send back a price before any work gets scheduled.

Free estimate

TanStack Query giving you trouble?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.