fix(query-core): ensure query refetches on mount/retry when status is error (#9728) (#9927)

* fix(query-core): ensure query refetches on mount/retry when status is error (#9728)

* fix: mark queries as invalidated on background errors instead of checking error status

- Remove error status check in shouldFetchOn
- Set isInvalidated: true in reducer when background error occurs (only if data exists)
- Add tests for staleTime: 'static' and non-static queries with background errors

This approach centralizes stale logic in isStale/isStaleByTime and prevents
regression where staleTime: 'static' queries would incorrectly refetch on
window focus after a background error.

* refactor: simplify isInvalidated logic in error case

Set isInvalidated: true unconditionally since queries with no data
are always considered stale per isStaleByTime logic.

* Apply suggestion from @TkDodo

* Apply suggestions from code review

* fix: eslint

* fix: disable retry in background error tests to prevent timeout

The tests were timing out because when refetch() throws an error, the
default retry mechanism (3 retries with exponential backoff) was being
triggered. With fake timers, the retry delays weren't being advanced,
causing the tests to hang.

Adding retry: false to both tests disables retries and allows them to
complete immediately after the error, which is appropriate for these
tests that specifically check background error behavior.

---------

Co-authored-by: Dominik Dorfmeister <[email protected]>

Author: xiangnuans

.changeset/open-keys-create.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/query-core': patch
+---
+
+Fix: Always treat existing data as stale when query goes into error state.

packages/query-core/src/__tests__/queryObserver.test.tsx

@@ -1394,6 +1394,87 @@ describe('queryObserver', () => {
     unsubscribe()
   })
 
+  test('should not refetchOnWindowFocus when staleTime is static and query has background error', async () => {
+    const key = queryKey()
+    let callCount = 0
+    const queryFn = vi.fn(async () => {
+      callCount++
+      if (callCount === 1) {
+        return 'data'
+      }
+      throw new Error('background error')
+    })
+
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn,
+      staleTime: 'static',
+      refetchOnWindowFocus: true,
+      retry: false,
+    })
+
+    const unsubscribe = observer.subscribe(() => undefined)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(queryFn).toHaveBeenCalledTimes(1)
+    expect(observer.getCurrentResult().data).toBe('data')
+    expect(observer.getCurrentResult().status).toBe('success')
+
+    await observer.refetch()
+    await vi.advanceTimersByTimeAsync(0)
+    expect(queryFn).toHaveBeenCalledTimes(2)
+    expect(observer.getCurrentResult().status).toBe('error')
+    expect(observer.getCurrentResult().data).toBe('data')
+
+    focusManager.setFocused(false)
+    focusManager.setFocused(true)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(queryFn).toHaveBeenCalledTimes(2)
+
+    unsubscribe()
+  })
+
+  test('should refetchOnWindowFocus when query has background error and staleTime is not static', async () => {
+    const key = queryKey()
+    let callCount = 0
+    const queryFn = vi.fn(async () => {
+      callCount++
+      if (callCount === 1) {
+        return 'data'
+      }
+      if (callCount === 2) {
+        throw new Error('background error')
+      }
+      return 'new data'
+    })
+
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn,
+      staleTime: 1000,
+      refetchOnWindowFocus: true,
+      retry: false,
+    })
+
+    const unsubscribe = observer.subscribe(() => undefined)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(queryFn).toHaveBeenCalledTimes(1)
+    expect(observer.getCurrentResult().data).toBe('data')
+    expect(observer.getCurrentResult().status).toBe('success')
+
+    await observer.refetch()
+    await vi.advanceTimersByTimeAsync(0)
+    expect(queryFn).toHaveBeenCalledTimes(2)
+    expect(observer.getCurrentResult().status).toBe('error')
+    expect(observer.getCurrentResult().data).toBe('data')
+
+    focusManager.setFocused(false)
+    focusManager.setFocused(true)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(queryFn).toHaveBeenCalledTimes(3)
+
+    unsubscribe()
+  })
+
   test('should set fetchStatus to idle when _optimisticResults is isRestoring', () => {
     const key = queryKey()
     const observer = new QueryObserver(queryClient, {

packages/query-core/src/query.ts

@@ -658,6 +658,9 @@ export class Query<
             fetchFailureReason: error,
             fetchStatus: 'idle',
             status: 'error',
+            // flag existing data as invalidated if we get a background error
+            // note that "no data" always means stale so we can set unconditionally here
+            isInvalidated: true,
           }
         case 'invalidate':
           return {

packages/react-query/src/__tests__/issue-9728.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from 'vitest'
+import { fireEvent, render } from '@testing-library/react'
+import * as React from 'react'
+import { ErrorBoundary } from 'react-error-boundary'
+import { queryKey } from '@tanstack/query-test-utils'
+import {
+  QueryClient,
+  QueryClientProvider,
+  QueryErrorResetBoundary,
+  useQuery,
+} from '..'
+
+describe('issue 9728', () => {
+  it('should refetch after error when staleTime is Infinity and previous data exists', async () => {
+    const key = queryKey()
+    const queryFn = vi.fn()
+    let count = 0
+
+    queryFn.mockImplementation(async () => {
+      count++
+      if (count === 2) {
+        throw new Error('Error ' + count)
+      }
+      return 'Success ' + count
+    })
+
+    const queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+          staleTime: Infinity,
+        },
+      },
+    })
+
+    function Page() {
+      const [_, forceUpdate] = React.useState(0)
+
+      React.useEffect(() => {
+        forceUpdate(1)
+      }, [])
+
+      const { data, refetch } = useQuery({
+        queryKey: key,
+        queryFn,
+        throwOnError: true,
+      })
+
+      return (
+        <div>
+          <div>Data: {data}</div>
+          <button onClick={() => refetch()}>Refetch</button>
+        </div>
+      )
+    }
+
+    function App() {
+      return (
+        <QueryErrorResetBoundary>
+          {({ reset }) => (
+            <ErrorBoundary
+              onReset={reset}
+              fallbackRender={({ resetErrorBoundary }) => (
+                <div>
+                  <div>Status: error</div>
+                  <button onClick={resetErrorBoundary}>Retry</button>
+                </div>
+              )}
+            >
+              <React.Suspense fallback={<div>Loading...</div>}>
+                <Page />
+              </React.Suspense>
+            </ErrorBoundary>
+          )}
+        </QueryErrorResetBoundary>
+      )
+    }
+
+    const { getByText, findByText } = render(
+      <React.StrictMode>
+        <QueryClientProvider client={queryClient}>
+          <App />
+        </QueryClientProvider>
+      </React.StrictMode>,
+    )
+
+    // 1. First mount -> Success
+    await findByText('Data: Success 1')
+    expect(queryFn).toHaveBeenCalledTimes(1)
+
+    // 2. Click Refetch -> Triggers fetch -> Fails (Error 2) -> ErrorBoundary
+    fireEvent.click(getByText('Refetch'))
+
+    // Wait for error UI
+    await findByText('Status: error')
+    expect(queryFn).toHaveBeenCalledTimes(2)
+
+    // 3. Click Retry -> Remounts
+    // Because staleTime is Infinity and we have Data from (1),
+    // AND we are in Error state.
+    fireEvent.click(getByText('Retry'))
+
+    // Should call queryFn again (3rd time) and succeed
+    await findByText('Data: Success 3')
+    expect(queryFn).toHaveBeenCalledTimes(3)
+  })
+})