fix(query-core): keep select error result stable when select throws the same error

.changeset/select-error-render-loop.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/query-core': patch
+---
+
+Keep the observer result stable when `select` throws the same error again, so an inline selector no longer forces a render loop.

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

@@ -534,6 +534,107 @@ describe('queryObserver', () => {
     })
   })
 
+  it('should not notify listeners when an unstable selector throws the same error', async () => {
+    const key = createKey()
+    const queryFn = () => Promise.resolve({ count: 1 })
+    const observer = new QueryObserver<{ count: number }, Error, number>(
+      queryClient,
+      {
+        queryKey: key,
+        queryFn,
+        select: () => {
+          throw new Error('selector error')
+        },
+      },
+    )
+    const results: Array<QueryObserverResult> = []
+    const unsubscribe = observer.subscribe((result) => {
+      results.push(result)
+    })
+
+    await vi.advanceTimersByTimeAsync(10)
+    const settled = results[results.length - 1]
+    const selectError = settled?.error
+    let notifications = results.length
+    expect(settled).toMatchObject({ status: 'error' })
+    expect(selectError).toBeInstanceOf(Error)
+
+    const expectSameError = async (
+      select: (data: { count: number }) => number,
+    ) => {
+      observer.setOptions({ queryKey: key, queryFn, select })
+      await vi.advanceTimersByTimeAsync(10)
+      expect(results).toHaveLength(notifications)
+      expect(observer.getCurrentResult().error).toBe(selectError)
+      expect(observer.getCurrentResult().errorUpdatedAt).toBe(
+        settled?.errorUpdatedAt,
+      )
+    }
+
+    await expectSameError(() => {
+      throw new Error('selector error')
+    })
+    await expectSameError(() => {
+      throw selectError
+    })
+
+    const changed = new Error('different error')
+    observer.setOptions({
+      queryKey: key,
+      queryFn,
+      select: () => {
+        throw changed
+      },
+    })
+    await vi.advanceTimersByTimeAsync(10)
+    notifications++
+
+    expect(results).toHaveLength(notifications)
+    expect(results[results.length - 1]?.error).toBe(changed)
+    expect(results[results.length - 1]?.errorUpdatedAt).toBeGreaterThan(
+      settled?.errorUpdatedAt ?? 0,
+    )
+
+    const withCause = new Error('different error', { cause: 'missing' })
+    observer.setOptions({
+      queryKey: key,
+      queryFn,
+      select: () => {
+        throw withCause
+      },
+    })
+    await vi.advanceTimersByTimeAsync(10)
+    notifications++
+    expect(results).toHaveLength(notifications)
+    expect(results[results.length - 1]?.error).toBe(withCause)
+
+    observer.setOptions({
+      queryKey: key,
+      queryFn,
+      select: () => {
+        throw new Error('different error', { cause: 'missing' })
+      },
+    })
+    await vi.advanceTimersByTimeAsync(10)
+    expect(results).toHaveLength(notifications)
+
+    observer.setOptions({
+      queryKey: key,
+      queryFn,
+      select: (data) => data.count,
+    })
+    await vi.advanceTimersByTimeAsync(10)
+
+    expect(results).toHaveLength(notifications + 1)
+    expect(results[results.length - 1]).toMatchObject({
+      status: 'success',
+      data: 1,
+      error: null,
+    })
+
+    unsubscribe()
+  })
+
   it('should not have isPlaceholderData true when selector throws on placeholder data', () => {
     const key = createKey()
     const queryFn = () => sleep(10).then(() => ({ count: 1 }))

packages/query-core/src/queryObserver.ts

@@ -73,6 +73,7 @@ export class QueryObserver<
     TQueryKey
   >
   #selectError: TError | null
+  #selectErrorUpdatedAt = 0
   #selectFn?: (data: TQueryData) => TData
   #selectResult?: TData
   // This property keeps track of the last query with defined data.
@@ -697,20 +698,27 @@ export class QueryObserver<
           data = replaceData(prevResult?.data, data, options)
           this.#selectResult = data
           this.#selectError = null
+          this.#selectErrorUpdatedAt = 0
         } catch (selectError) {
-          this.#selectError = selectError as TError
+          // A new inline select throws a new object on every render. Replacing
+          // the stored error refreshes errorUpdatedAt and notifies subscribers.
+          if (selectErrorChanged(this.#selectError, selectError)) {
+            this.#selectError = selectError as TError
+            this.#selectErrorUpdatedAt = Date.now()
+          }
         }
       }
     } else if (data === undefined) {
       // a stored select error belongs to previously selected data; once that
       // data is gone (query switch or reset), it must not leak into this result
       this.#selectError = null
+      this.#selectErrorUpdatedAt = 0
     }
 
     if (this.#selectError) {
       error = this.#selectError
       data = this.#selectResult
-      errorUpdatedAt = Date.now()
+      errorUpdatedAt = this.#selectErrorUpdatedAt
       status = 'error'
       isPlaceholderData = false
     }
@@ -974,3 +982,34 @@ function isStale(
     query.isStaleByTime(resolveQueryValue(options.staleTime, query))
   )
 }
+
+/**
+ * Reports whether a value just thrown by `select` should replace the stored select error.
+ * A new `Error` with the same name, message, cause, and own fields is the same failure.
+ * That keeps `errorUpdatedAt` stable when an inline selector throws again on the next render.
+ * @param previous - The select error already stored, if there is one.
+ * @param next - The value just thrown by `select`.
+ * @returns `true` if `next` should replace `previous`.
+ */
+function selectErrorChanged(previous: unknown, next: unknown): boolean {
+  if (Object.is(previous, next)) {
+    return false
+  }
+
+  if (!(previous instanceof Error) || !(next instanceof Error)) {
+    return true
+  }
+
+  if (
+    previous.name !== next.name ||
+    previous.message !== next.message ||
+    !Object.is(previous.cause, next.cause)
+  ) {
+    return true
+  }
+
+  return !shallowEqualObjects(
+    previous as unknown as Record<string, any>,
+    next as unknown as Record<string, any>,
+  )
+}

packages/react-query/src/__tests__/useQuery.test.tsx

@@ -771,6 +771,63 @@ describe('useQuery', () => {
     expect(runs).toBe(2)
   })
 
+  it('should not loop when an inline selector throws and the query renders a stateful child', async () => {
+    const key = createKey()
+    let renders = 0
+
+    function Child() {
+      const [ready, setReady] = React.useState(false)
+
+      React.useEffect(() => {
+        setReady(true)
+      }, [])
+
+      return <span>{ready ? 'ready' : 'waiting'}</span>
+    }
+
+    function Page() {
+      renders++
+      if (renders > 20) {
+        throw new Error('render loop')
+      }
+
+      const [, rerender] = React.useReducer(() => ({}), {})
+      const state = useQuery({
+        queryKey: key,
+        queryFn: (): { result?: Array<string> } => ({}),
+        select: (data) => {
+          if (data.result === undefined) {
+            throw new TypeError(
+              "Cannot read properties of undefined (reading 'map')",
+            )
+          }
+          return data.result
+        },
+      })
+
+      return (
+        <div>
+          <div>{state.status}</div>
+          <Child />
+          <button onClick={rerender}>rerender</button>
+        </div>
+      )
+    }
+
+    const rendered = renderWithClient(queryClient, <Page />)
+
+    await vi.advanceTimersByTimeAsync(0)
+    rendered.getByText('error')
+    rendered.getByText('ready')
+    const settled = renders
+
+    fireEvent.click(rendered.getByRole('button', { name: 'rerender' }))
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(renders).toBe(settled + 1)
+    rendered.getByText('error')
+  })
+
   it('should track properties and only re-render when a tracked property changes', async () => {
     const key = createKey()
     const states: Array<UseQueryResult<string>> = []