Debugging Zombie Cache Entries in TanStack Query

Let’s talk about a weird one: zombie cache entries in TanStack Query. It’s not a common bug, but when it hits, it can be super confusing. You’re fetching data, your UI looks fine, but somewhere in the background, old, stale data is just… hanging out. Unused, but not gone. Like a ghost in the machine. We’re going to figure out how to spot these things and put them to rest.

What Exactly Are Zombie Cache Entries?

Think of your TanStack Query cache like a busy pantry. When you request an item (data), the pantry manager (TanStack Query) checks if it’s already there. If it is, great, instant snack. If not, they go fetch it and put it away. Now, imagine some items get put away, but the pantry manager forgets to update the inventory list, or worse, never throws away expired items. These are your zombie entries. They exist, but they’re effectively useless or even misleading.

In TanStack Query terms, a zombie entry is usually a query that’s still in the cache but has no active observers. No component is actively requesting that data. Normally, TanStack Query has garbage collection to clean these up after a certain cacheTime. But sometimes, things can get sticky.

How Do They Show Up?

This is the tricky part because they often don’t cause immediate visible errors. You might notice:

Stale data appearing unexpectedly: A component re-renders, and suddenly it’s showing data that should have been cleared or updated.
Slightly longer fetch times than expected: Even though you think the data should be cached, a refetch might be happening.
Increased memory usage: While less common to directly observe, a large number of zombie entries could contribute.
Confusion during development: You clear your network cache, but TanStack Query’s cache seems to be holding onto something it shouldn’t.

The Debugging Toolkit

To combat these spectral entries, we need some tools. Fortunately, TanStack Query provides excellent developer tools.

1. TanStack Query Devtools

This is your primary weapon. If you’re not using the Devtools, start now. They provide a live, interactive view of your cache.

Install them like so:

1
// In your React app's entry point (e.g., App.js or index.js)
2
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
3

4
function App() {
5
  return (
6
    <div>
7
      {/* Your app components */}
8
      <ReactQueryDevtools initialIsOpen={false} />
9
    </div>
10
  );
11
}
12

13
export default App;

With the Devtools open, you’ll see a list of all your queries. Look for queries that:

Have a status of inactive but are still present.
Have a dataUpdatedAt timestamp that seems very old, but the query is still listed.
You might not recognize the query key at all, indicating it’s orphaned.

2. Understanding `queryClient.removeQueries`

This method is crucial. It allows you to manually clear queries from the cache.

1
import { useQueryClient } from '@tanstack/react-query';
2

3
function MyComponent() {
4
  const queryClient = useQueryClient();
5

6
  const clearStaleData = () => {
7
    // Remove all inactive queries
8
    queryClient.removeQueries({ active: false });
9
    // Or remove a specific query by its key
10
    // queryClient.removeQueries(['todos']);
11
    console.log('Cleared stale queries.');
12
  };
13

14
  return (
15
    <button onClick={clearStaleData}>
16
      Clear Stale Data
17
    </button>
18
  );
19
}

Common Causes and Solutions

Incorrect cacheTime Configuration: The default cacheTime is usually quite generous (5 minutes for inactive, 24 hours for active). If you’ve lowered it too much, or if there’s a misunderstanding of its purpose (it’s for inactive queries without observers), you might be clearing things too aggressively. Remember, cacheTime is the duration an inactive query is kept in the cache before garbage collection.
Unmounted Components Holding References: Sometimes, a component might unmount but still hold a stale reference to a query that, for some reason, isn’t being properly dereferenced by the query client. This is rare but can happen with complex component lifecycles or custom hooks that interact deeply with TanStack Query.
Manual Cache Manipulation Gone Wrong: If you’re using queryClient.setQueryData or queryClient.getQueryData extensively and not managing the lifecycle correctly, you could inadvertently create orphaned entries.
Long-Running Background Tasks: If you have background tasks (e.g., using useEffect with setInterval that doesn’t clean up properly) that trigger queries, they might leave behind stale data if the component that initiated them unmounts. Always ensure your useEffect cleanup functions are robust.

Proactive Measures

Leverage queryClient.getQueryCache().subscribe(): For deeper insights, you can subscribe to cache events.

1
import { useEffect } from 'react';
2
import { useQueryClient } from '@tanstack/react-query';
3

4
function CacheMonitor() {
5
  const queryClient = useQueryClient();
6

7
  useEffect(() => {
8
    const unsubscribe = queryClient.getQueryCache().subscribe(event => {
9
      // console.log('Cache Event:', event.query.queryKey, event.type);
10
      if (event.type === 'inactive') {
11
        console.warn(`Query became inactive: ${event.query.queryKey}`);
12
      }
13
      if (event.type === 'removed') {
14
        console.log(`Query removed: ${event.query.queryKey}`);
15
      }
16
    });
17

18
    return () => unsubscribe(); // Cleanup
19
  }, [queryClient]);
20

21
  return null; // This component doesn't render anything
22
}

This gives you real-time feedback on query lifecycle changes.

Review queryCache Options: Be mindful of your global QueryClient options, especially cacheTime and queryCache.gcTime (garbage collection time).

1
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
2

3
const queryClient = new QueryClient({
4
  defaultOptions: {
5
    queries: {
6
      // Cache for 10 minutes after data becomes inactive
7
      cacheTime: 1000 * 60 * 10,
8
      // garbage collect inactive queries after 30 minutes
9
      gcTime: 1000 * 60 * 30,
10
    },
11
  },
12
});
13

14
// ... provide queryClient to your app

The gcTime is especially relevant for removing truly abandoned queries.

Conclusion

Zombie cache entries are rare but can be frustrating. By using the TanStack Query Devtools effectively, understanding cache lifecycle options, and employing careful debugging techniques like removeQueries and cache subscriptions, you can keep your cache clean and your application running smoothly. Happy debugging!