Race condition between useQuery and getQueryData() during cache invalidation in polling scenarios

[iicdii]

Note: This is being posted as a Discussion because it describes an unreproducible bug that occurs intermittently in production environments.

Bug Report

There's a race condition between useQuery hooks and direct getQueryData() calls during cache invalidation, specifically when using polling mechanisms that frequently call invalidateQueries. Despite parent components using useQuery with conditional rendering that should prevent child component rendering when data is unavailable, child components using getQueryData() still throw "Right side of assignment cannot be destructured" errors.

Steps to reproduce

Context: Polling-based cache invalidation

Our app uses a polling mechanism that calls invalidateQueries every 3 seconds:

// Parent component with protective conditional rendering
const CartPage = () => {
  const { data } = useFetchCart(true);
  
  if (!data) {
    return <EmptyCartTemplate />; // Should prevent child rendering
  }
  
  return <GroupOrderCartTemplateContainer />; // Only renders when data exists
};

// Child component using direct cache access
const GroupOrderCartTemplateContainer = () => {
  const cartQueryData = useGetCartQueryData<FetchCartResponse>(); // Throws error!
  // ... rest of component
};

// Polling hook that triggers the issue
const useSyncGroupOrderCartQuery = () => {
  const queryClient = useQueryClient();
  const cartQueryData = useGetCartQueryData<FetchCartResponse | null>();
  
  useFetchCartUpdateInfo(cartQueryData?.groupInfo?.groupCartVersion || '', {
    refetchInterval: 3_000, // Polls every 3 seconds
    meta: {
      onSuccess: (data) => {
        if (data?.status === 'UPDATED' || data?.status === 'EXPIRED') {
          // This invalidation causes the race condition
          queryClient.invalidateQueries({ queryKey: cartQueryKeys.fetchCart().queryKey });
        }
      },
    },
  });
};

// useGetCartQueryData implementation
export const useGetCartQueryData = <T>() => {
  const queryClient = useQueryClient();
  const cartQueryData = queryClient.getQueryData<T>(cartQueryKeys.fetchCart().queryKey);

  if (cartQueryData === undefined) {
    throw new UndefinedCartDataError(); // This throws despite parent having data
  }

  return cartQueryData;
};

Reproduction steps:

1. Set up a parent component using useQuery with conditional rendering
2. Create a child component that uses getQueryData() directly
3. Implement a polling mechanism that calls invalidateQueries every 3 seconds
4. Navigate to the page and wait for polling to trigger invalidation
5. Observe intermittent errors where child component throws while parent still renders

Expected behavior

When a parent component using useQuery conditionally renders based on data availability, child components should never be rendered in a state where the same cached data is unavailable via getQueryData(). Both should access the same underlying cache consistently.

Your minimal, reproducible example

Note: This is an intermittent race condition that occurs in production environments but is difficult to reproduce consistently in isolated examples due to its timing-dependent nature.

Production Context:

• High-traffic mobile web application serving millions of users
• Concurrent polling mechanisms (3-second intervals)
• Real-world network latency variations

Stackblitz Demo: https://stackblitz.com/edit/tanstack-query-um5nzlel?file=src%2Findex.jsx
This demo shows the architectural pattern that causes the issue, but may not consistently reproduce the error due to the race condition's timing dependency.

Production Evidence:

• Error frequency: 11,000+ occurrences over 4 months (average 92 errors per day)
• Affected users: 8,600+ unique users impacted
• Error pattern: 99% occur in cart-related components using getQueryData()

The core issue remains: useQuery and getQueryData() can return inconsistent values for the same cache key during invalidation cycles, despite both supposedly accessing the same underlying cache.

Screenshots or Videos

Production error monitoring shows "TypeError: Right side of assignment cannot be destructured" occurring specifically in components using getQueryData(), while parent components using useQuery successfully render with data. The error consistently occurs at line positions where destructuring assignment is attempted on undefined values returned by getQueryData().

Platform

• OS: iOS, Android
• Browser: Mobile Safari, Chrome
• Version: Primarily mobile browsers on recent Safari / Chrome Mobile WebView

TanStack Query information

• TanStack Query version: v4.36.1
• Adapter: React
• TypeScript version: v5.0.4

Additional context

Production Error Analysis

Our error monitoring reveals consistent patterns:

• User journey: Most errors occur during cart operations with active polling
• Error persistence: Issue has been ongoing for 4+ months, indicating it's not an edge case

The Race Condition Pattern

The issue occurs when:

1. Polling API responds with status requiring cache invalidation
2. invalidateQueries called → cache marked as stale/invalidated
3. React Query starts refetch for the invalidated query
4. Parent component's useQuery still maintains previous data (React state)
5. Child component renders because parent condition passes
6. Child's getQueryData() returns undefined (cache already invalidated)
7. Error thrown in child component

Key Question

Is this expected behavior where useQuery and getQueryData() can return different values for the same cache key during invalidation? The documentation suggests they should access the same underlying cache, but our production data shows clear timing inconsistencies affecting thousands of users.

Current Workaround: Replace all getQueryData() calls with useQuery hooks, but this feels like it shouldn't be necessary given both should access the same cache.

Root Cause Hypothesis: The issue appears to be that useQuery maintains React state through QueryObserver subscriptions while getQueryData() directly accesses cache, creating a window where they're out of sync during invalidation + refetch cycles.

[TkDodo]

I can only say that getQueryData is not meant to be called during a component render, as it’s not reactive by itself. The component that calls getQueryData will only re-render when the parent re-renders, not when new data comes into the cache. That creates an implicit depdency which should be avoided.

The better fix is being explicit about dependencies, either by passing data down as a prop or by calling useQuery again in the child component.

That said, if GroupOrderCartTemplateContainer only renders when data is in the cache (given the conditional rendering), I don’t see a way how getQueryData can return undefined. A refetchInterval shouldn’t change that, and neither should query invalidation, as those don’t remove data from the cache.

The issue appears to be that useQuery maintains React state through QueryObserver subscriptions while getQueryData() directly accesses cache, creating a window where they're out of sync during invalidation + refetch cycles.

Unless your observer uses placeholderData or select or something similar that changes what the observer returns, data should be the same as data in the cache. Have you tried adding a log statement into CartPage where you log the result of queryClient.getQueryData ?