TanStack Query v5 - Expert Troubleshooting

Assumption: You know

useQuery

basics. This covers what breaks in production.

Before Using React Query: Strategic Assessment

Ask yourself these questions BEFORE adding useQuery:

1. Data Source Analysis

Where does this data come from?
- URL params/path → Framework loader (Next.js, Remix), not React Query
- Computation/derivation → useMemo, not React Query
- Form input → React Hook Form, not React Query
- REST/GraphQL → React Query ✅

2. Update Frequency & Caching Strategy

How often does this data change?
- Real-time (>1/sec) → WebSocket + Zustand (React Query overhead too high)
- Frequent (<1/min) → React Query with aggressive staleTime (30s-1min)
- Moderate (5-30min) → React Query standard (staleTime: 5min)
- Infrequent (>1hr) → React Query with long staleTime (30min+)

3. Cost of Stale Data

What happens if user sees old data?
- Critical (money, auth tokens) → staleTime: 0 (always fresh)
- Important (user content, messages) → staleTime: 1-5min
- Nice-to-have (analytics, recommendations) → staleTime: 30min+

Critical Decision: When NOT to Use React Query

Need data fetching?
│
├─ Data from URL (search params, path) → DON'T use queries
│   └─ Use framework loaders (Next.js, Remix) or URL state
│      WHY: Queries cache by key, URL is already your cache key
│
├─ Derived/computed data → DON'T use queries
│   └─ Use useMemo or Zustand
│      WHY: No server, no stale data, no refetch needed
│
├─ Form state → DON'T use queries
│   └─ Use React Hook Form or controlled state
│      WHY: Forms are local state, not server cache
│
├─ WebSocket/realtime data → MAYBE use queries
│   ├─ High-frequency updates (> 1/sec) → DON'T use queries (use Zustand)
│   └─ Low-frequency (<1/min) → Use queries with manual updates
│      WHY: Queries designed for request/response, not streaming
│
└─ REST/GraphQL server state → USE queries
    (This is what React Query is for)

The trap: Developers use React Query for everything. It's a server cache, not a state manager.

Breaking Changes: v4 → v5 Migration Gotchas

❌ #1:

cacheTime

Renamed to

gcTime

Problem: Silent failure - code runs but cache doesn't work as expected

typescript

// WRONG - v4 syntax, silently ignored in v5
useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  cacheTime: 10 * 60 * 1000,  // ❌ Ignored in v5
})

// CORRECT - v5 syntax
useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  gcTime: 10 * 60 * 1000,  // ✅ Garbage collection time
})

Why it breaks: TypeScript won't error if using

any

or loose types. Cache appears to work but garbage collects immediately.

Why this is deceptively hard to debug: No error messages—app runs perfectly. Cache appears functional initially. Only after 5+ minutes in production do you notice data refetching too frequently and Network tab lighting up. DevTools shows query has 0ms gcTime but you SET 10 minutes. The property is silently ignored—no warnings, no TypeScript errors. Takes 20-30 minutes of cache inspection comparing v4 docs to v5 docs to realize the property was renamed. Searches for "cacheTime not working" find v4 results, not v5 migration notes.

❌ #2:

isLoading

Removed, Use

isPending

Problem: Loading spinners disappear too early

typescript

// WRONG - v4 syntax
const { isLoading } = useQuery(...)
if (isLoading) return <Spinner />  // ❌ isLoading undefined in v5

// CORRECT - v5 syntax
const { isPending } = useQuery(...)
if (isPending) return <Spinner />  // ✅ Shows while query pending

Why different:

```
isLoading
```
(v4):
```
true
```
only for first fetch (no cached data)
```
isPending
```
(v5):
```
true
```
for first fetch + refetches (more accurate)

Migration trap: If you have cached data and refetch,

isPending

stays

true

but

isLoading

was

false

. UI shows stale data + spinner in v5.

Why this is deceptively hard to debug:

isLoading

is undefined but JavaScript doesn't error—

if (undefined)

is falsy, so spinner never shows. UI appears to work in initial testing (data loads fine). Only in specific edge case—user navigates away and back with cached data—does the bug appear: no loading state during refetch. Users report "page feels broken" but can't reproduce consistently. DevTools shows

isLoading: undefined

but that's easy to miss in large state object. Takes 15-20 minutes to realize v5 removed the property entirely and you need

isPending

instead.

❌ #3:

keepPreviousData

Removed, Use

placeholderData

Problem: Pagination breaks - flickers on page change

typescript

// WRONG - v4 syntax
useQuery({
  queryKey: ['todos', page],
  queryFn: () => fetchTodos(page),
  keepPreviousData: true,  // ❌ Removed in v5
})

// CORRECT - v5 syntax
useQuery({
  queryKey: ['todos', page],
  queryFn: () => fetchTodos(page),
  placeholderData: (previousData) => previousData,  // ✅ Function form
})

Why it breaks:

keepPreviousData: true

was boolean.

placeholderData

is data OR function. If you pass

true

, TypeScript error but runtime breaks.

❌ #4: Query Functions Must Return Non-Void

Problem: Mutations that don't return data break

typescript

// WRONG - void return breaks v5
queryFn: async () => {
  await api.deleteTodo(id)  // ❌ Returns void
}

// CORRECT - return something
queryFn: async () => {
  await api.deleteTodo(id)
  return { success: true }  // ✅ Return data
}

Why it breaks: v5 type system requires

Promise<TData>

, not

Promise<void>

. Silent runtime error if using

any

Performance Pitfalls

❌ Infinite Refetch Loop

Problem: Query refetches forever, browser freezes

typescript

// WRONG - creates infinite loop
useQuery({
  queryKey: ['user', user],  // ❌ Object in key
  queryFn: () => fetchUser(user.id),
})

// WHY IT LOOPS:
// 1. Query runs, gets data
// 2. Component re-renders
// 3. New `user` object created (different reference)
// 4. Key changes → query refetches
// 5. Goto 1 (infinite)

// CORRECT - use primitive values
useQuery({
  queryKey: ['user', user.id],  // ✅ String is stable
  queryFn: () => fetchUser(user.id),
})

Detection: React DevTools shows component re-rendering every frame. Network tab shows identical requests hammering server.

Why this is deceptively hard to debug: Page loads fine initially—first query succeeds. Then browser tab becomes unresponsive. CPU spikes to 100%. Network tab shows 50+ identical requests per second. React DevTools Profiler is unusable (too many renders). The cause—object reference in queryKey—is invisible in the network requests (they all look identical). Error isn't obvious: no stack trace, no warning, just performance death. Takes 10-15 minutes to realize it's React Query, then another 10-15 to isolate which query. Only after adding

console.log

to every query do you see one logging hundreds of times. The fix (extract primitive from object) is obvious once found, but finding the culprit query in a codebase with 50+ queries is the hard part.

❌ Stale Data Trap

Problem: Data never updates despite changes on server

typescript

// WRONG - data stuck in cache
useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  staleTime: Infinity,  // ❌ Never marks stale
})

// User adds todo on another tab → never sees it

// CORRECT - reasonable staleTime
useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  staleTime: 5 * 60 * 1000,  // ✅ 5 minutes
})

Trade-off:

```
staleTime: 0
```
→ Refetch on every focus/mount (expensive)
```
staleTime: Infinity
```
→ Never refetch (stale data)
```
staleTime: 5min
```
→ Balance (refetch after 5min of inactivity)

Why this is deceptively hard to debug: Works perfectly in development—you refresh constantly, clearing cache. In production, users keep tabs open for hours. They report "data doesn't update" but you can't reproduce (your dev habits differ). When you check DevTools, query shows fresh data (because you just opened DevTools, triggering window focus refetch if you have default settings). The user's

staleTime: Infinity

is buried in a hook 3 files deep. No error, no warning. You check the API—returns fresh data. You check network—no requests being made (that's the clue, but easy to miss). Takes 20-30 minutes of user reproduction videos to notice they never see network requests after initial load. Only then do you search the codebase for

staleTime

settings.

❌ Over-Invalidation

Problem: Unrelated data refetches on every mutation

typescript

// WRONG - nukes entire cache
onSuccess: () => {
  queryClient.invalidateQueries()  // ❌ Refetches EVERYTHING
}

// User updates profile → todos, posts, comments all refetch

// CORRECT - targeted invalidation
onSuccess: () => {
  queryClient.invalidateQueries({ queryKey: ['user', userId] })  // ✅ Only user
}

Why it hurts: 100 queries in cache → 100 network requests on every mutation. Kills mobile users.

Decision Frameworks

When to Use Optimistic Updates vs Invalidation

Mutation completes...
│
├─ Simple list append/prepend → Optimistic (useMutationState)
│   └─ Add todo, add comment, add item
│      WHY: No complex logic, just show pending item
│
├─ Complex computed data → Invalidation
│   └─ Change affects aggregates, filters, sorts
│      WHY: Server computes, client doesn't duplicate logic
│
├─ Risk of conflicts → Invalidation
│   └─ Multiple users editing same data
│      WHY: Optimistic update may be wrong, let server resolve
│
└─ Must feel instant → Optimistic + rollback on error
    └─ Toggle like, toggle favorite
       WHY: User expects immediate feedback

React Query vs SWR

Choose React Query when:
✅ Need fine-grained cache control (gc, stale times)
✅ Complex invalidation patterns
✅ Optimistic updates with rollback
✅ Infinite queries (pagination)
✅ Already using TanStack ecosystem (Table, Router)

Choose SWR when:
✅ Simpler API (less configuration)
✅ Automatic revalidation on focus is main use case
✅ Smaller bundle size priority
✅ Using Next.js (first-party support)

Real-world: React Query wins for complex apps, SWR wins for simple dashboards.

SSR Hydration Patterns (Next.js App Router)

❌ Common Hydration Mismatch

typescript

// WRONG - server renders loading, client renders data
function Page() {
  const { data, isPending } = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  })

  if (isPending) return <div>Loading...</div>  // ❌ Mismatch
  return <div>{data.map(...)}</div>
}

// SERVER: Renders "Loading..."
// CLIENT: Has cached data → renders list
// RESULT: Hydration error

✅ Correct Pattern with Prefetch

typescript

// app/page.tsx (Server Component)
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'

export default async function Page() {
  const queryClient = new QueryClient()

  // Prefetch on server
  await queryClient.prefetchQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  })

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <TodoList />  {/* Client Component */}
    </HydrationBoundary>
  )
}

// components/TodoList.tsx (Client Component)
'use client'

export function TodoList() {
  const { data } = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  })

  // No isPending check - data guaranteed from server
  return <div>{data.map(...)}</div>
}

Why it works: Server prefetches, client hydrates with same data, no mismatch.

Debugging Commands

Find refetch loops

typescript

// Add to QueryClient
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      onSuccess: (data, query) => {
        console.count(`Refetch: ${query.queryKey}`)
        // If count > 10 in 1 second → infinite loop
      }
    }
  }
})

Visualize cache state

typescript

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

// Add to app
<ReactQueryDevtools initialIsOpen={false} />
// Click query → see refetch count, staleness, gc time

Test staleTime behavior

typescript

// Force immediate stale (for testing)
queryClient.invalidateQueries({ queryKey: ['todos'] })

// Check if query is stale
const state = queryClient.getQueryState(['todos'])
console.log(state?.isInvalidated)  // true = will refetch on next mount

Error Recovery Procedures

When Hydration Mismatch Occurs (SSR)

Recovery steps:

Verify data equality: Add
```
console.log(JSON.stringify(data))
```
in server and client components
Check prefetch completion: Inspect
```
dehydrate(queryClient)
```
output—should contain queries object
Confirm queryKey match: Server and client must use EXACT same key (including array order)

Fallback: If still mismatching, bypass prefetch and use

initialData

from server props:

typescript

// Server passes data via props
export default function Page() {
  const data = await fetchTodos()
  return <TodoList initialTodos={data} />
}

// Client receives and uses as initialData
function TodoList({ initialTodos }) {
  const { data } = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    initialData: initialTodos,  // Hydrates without mismatch
  })
}

When Infinite Refetch Loop Detected

Recovery steps:

Add refetch logging:
```
console.count(\
```
Refetch: ${JSON.stringify(queryKey)}`)` in queryFn
Identify the culprit: Check which count exceeds 10 in first 2 seconds
Extract primitives from queryKey: Replace objects/arrays with IDs/strings

Fallback: If key MUST contain object (rare), memoize it AND disable

structuralSharing

typescript

const stableKey = useMemo(() => ['user', user], [user.id])
useQuery({
  queryKey: stableKey,
  queryFn: () => fetchUser(user.id),
  structuralSharing: false,  // Prevents reference comparison issues
})

When Stale Data Persists

Recovery steps:

Check
```
staleTime
```
setting: Search codebase for
```
staleTime: Infinity
```
or very large values

Force invalidation:

queryClient.invalidateQueries({ queryKey: ['your-key'] })

Verify refetch: Check Network tab for request after invalidation

Fallback: If data still stale, cache may be corrupted → clear and refetch:

typescript

queryClient.removeQueries({ queryKey: ['your-key'] })
queryClient.refetchQueries({ queryKey: ['your-key'] })

Or nuclear option:

queryClient.clear()

(clears entire cache)

When v4→v5 Migration Breaks Silently

Recovery steps:

Enable strict TypeScript: Add
```
strict: true
```
to
```
tsconfig.json
```
to catch removed properties

Search for v4 property names:

grep -r "cacheTime\|isLoading\|keepPreviousData" src/

Replace with v5 equivalents: Use find-replace for codebase-wide fixes

Fallback: If TypeScript still doesn't catch it, add runtime warning in development:

typescript

// In QueryClient setup
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // @ts-ignore - intentionally check for v4 props
      ...(process.env.NODE_ENV === 'development' && {
        // Warn if someone passes v4 props
        onError: (err, query) => {
          if ('cacheTime' in query) console.warn('⚠️ cacheTime removed in v5, use gcTime')
          if ('isLoading' in query) console.warn('⚠️ isLoading removed in v5, use isPending')
        }
      })
    }
  }
})

When to Load Full Reference

MANDATORY - READ ENTIRE FILE:

references/v5-features.md

when:

Using 3+ v5-specific features simultaneously (useMutationState, throwOnError, infinite queries)
Need complete API reference for 5+ advanced hook options (select, placeholderData, notifyOnChangeProps)
Implementing complex patterns (optimistic updates with rollback, parallel/dependent queries, suspense mode)
Building custom hooks wrapping React Query with 4+ configuration options

MANDATORY - READ ENTIRE FILE:

references/migration-guide.md

when:

Migrating codebase with 10+ query usages from v4 to v5
Need exhaustive breaking changes checklist (20+ items to verify)
Encountering 3+ different v4→v5 migration errors
Setting up automated migration with codemods for large codebase (100+ queries)

Do NOT load references for:

Single breaking change fix (use this core framework's Breaking Changes section)
Basic troubleshooting (infinite loops, stale data, hydration—covered in core)
Simple optimistic update (use Decision Frameworks section)

Resources

Official Docs: https://tanstack.com/query/latest (for API reference)
This Skill: Production issues, migration gotchas, decision frameworks

tanstack-query

NPX Install

Tags

SKILL.md Content

TanStack Query v5 - Expert Troubleshooting

Before Using React Query: Strategic Assessment

1. Data Source Analysis

2. Update Frequency & Caching Strategy

3. Cost of Stale Data

Critical Decision: When NOT to Use React Query

Breaking Changes: v4 → v5 Migration Gotchas

❌ #1:
`cacheTime`
Renamed to
`gcTime`

❌ #2:
`isLoading`
Removed, Use
`isPending`

❌ #3:
`keepPreviousData`
Removed, Use
`placeholderData`

❌ #4: Query Functions Must Return Non-Void

Performance Pitfalls

❌ Infinite Refetch Loop

❌ Stale Data Trap

❌ Over-Invalidation

Decision Frameworks

When to Use Optimistic Updates vs Invalidation

React Query vs SWR

SSR Hydration Patterns (Next.js App Router)

❌ Common Hydration Mismatch

✅ Correct Pattern with Prefetch

Debugging Commands

Find refetch loops

Visualize cache state

Test staleTime behavior

Error Recovery Procedures

When Hydration Mismatch Occurs (SSR)

When Infinite Refetch Loop Detected

When Stale Data Persists

When v4→v5 Migration Breaks Silently

When to Load Full Reference

Resources