Learning TanStack Query - Devtools & Debugging

#Introduction

TanStack Query handles so much automatically — refetch, retry, invalidation — that when its behavior isn't what you expect, you need extra eyes. Fortunately this library has React Query Devtools: a panel that shows the entire cache contents and the status of each query in real time.

Episode 17 teaches how to use the devtools, then troubleshooting for the four most common problems developers run into.

#React Query Devtools

#Installing Devtools

Devtools were already installed in episode 0. All that's left is rendering the component in the application:

Installing ReactQueryDevtools

import { ReactQueryDevtools } from "@tanstack/react-query-devtools"
 
function App() {
  return (
    <>
      <Todos />
      <ReactQueryDevtools initialIsOpen={false} />
    </>
  )
}

ReactQueryDevtools adds a debug panel that can be opened from the corner of the screen. initialIsOpen={false} keeps the panel closed at the start. Devtools don't change the application's behavior — they're just an observation window.

#Key Devtools Features

The devtools panel provides information you can't see from code alone:

• Query explorer: a list of all active queries, complete with queryKey.
• Status per query: fresh, stale, fetching, paused, or inactive.
• Cache contents: the raw data stored for each query.
• Manual actions: refetch and invalidate buttons per query.
• Fetch history: the number of fetches and observers for each key.

queryKey: ["todos"]        → status: stale, 2 observers, 1 fetch
queryKey: ["todos", 5]     → status: fetching, 1 observer
queryKey: ["config"]       → status: fresh, 0 observers (inactive)

The line queryKey: ["todos"] → status: stale shows an example query status. If a query isn't refetching as expected, this panel is the first place to check its status and staleTime.

#Common Troubleshooting

#Query Not Refetching

The most common symptom: a query runs once and is never refetched, even though the data has changed on the server. Possible causes:

1. staleTime too large → data is always considered fresh
2. refetchOnWindowFocus false → no trigger
3. no invalidateQueries → the cache is never marked stale

Cause number 1 — staleTime too large — happens most often. Remember the principle from episode 7: refetch triggers only work on stale queries. Check staleTime, or invalidate manually in devtools to confirm the mechanism works.

#Infinite Loop

A query that refetches endlessly usually comes from a queryFn that changes something that is also part of the queryKey:

queryFn that changes the queryKey

// berbahaya: state yang diubah menyebabkan key berubah → fetch → berubah lagi
const { data } = useQuery({
  queryKey: ["todos", filter],
  queryFn: () => fetchTodos(filter),
})

If filter changes inside queryFn or is affected by its result, the key changes, a new fetch runs, the key changes again — that's the infinite loop. queryFn must be pure: read parameters from queryKey, never change them. Also make sure a new function object isn't created inside render in a way that changes the dependency.

#Error Serialization

If the error from queryFn can't be serialized — for example an Error with non-standard properties when persisting the cache — hydration will fail. Make sure the error thrown is a simple Error:

Errors that are safe to serialize

throw new Error("Gagal mengambil data")
throw new ApiError(status, "Pesan untuk user")

throw new Error("...") creates an error that is safe for serialization. ApiError above is a subclass whose fields are strings and numbers — no circular references or functions that would cause problems when the cache is persisted.

#Cache Memory Leak

A very large gcTime plus queries frequently created with unique keys can pile up in memory. The solution: make sure gcTime is reasonable, limit dynamically created queries, and enable devtools to monitor the number of cache entries. If the cache bloats, consider data normalization from episode 13.

#Closing

Episode 17 completed your debugging toolkit: React Query Devtools for observing the cache and statuses in real time, plus handling four classic problems — queries that don't refetch, infinite loops, error serialization, and cache memory leaks.

Key takeaways:

• ReactQueryDevtools shows the cache, statuses, and fetch counts.
• Devtools provide manual refetch and invalidate per query.
• staleTime too large causes a query to never refetch.
• A queryFn that changes the queryKey triggers an infinite loop.
• Throw a simple Error so it's safe for cache serialization.
• Monitor the number of cache entries to prevent memory leaks.

In the next episode, episode 18, we will discuss testing — creating a test-specific QueryClient with retry: false, using testing-library and renderHook, mocking the API with MSW, testing loading, success, and error states, and fake timers for refetchInterval.