Retry suspense failures
A query configured with suspense throws during rendering, and the UI needs a retry action that clears both the displayed boundary error and TanStack Query's error state.
TanStack · Hook
useQueryErrorResetBoundary
useQueryErrorResetBoundary exposes a reset function for coordinating TanStack Query errors with an error boundary. It resets errors within the nearest QueryErrorResetBoundary, or globally when no boundary exists.
How it works
Call the hook inside a component and use its reset function as the reset callback for an error boundary. The reset affects query errors in the nearest QueryErrorResetBoundary; without one, it applies globally.
Syntax
function useQueryErrorResetBoundary(): QueryErrorResetBoundaryValue;Returns
QueryErrorResetBoundaryValue
Key points
- The hook takes no arguments and returns a QueryErrorResetBoundaryValue.
- Its reset behavior is scoped to the nearest QueryErrorResetBoundary.
- With no surrounding boundary, query-error resets apply globally.
Common mistakes
- Without a surrounding QueryErrorResetBoundary, reset is global rather than limited to a component subtree.
Example: Reset query errors from an error boundary
import { ErrorBoundary } from 'react-error-boundary'
import { useQueryErrorResetBoundary } from '@tanstack/react-query'
function App({ children }: { children: React.ReactNode }) {
const { reset } = useQueryErrorResetBoundary()
return (
<ErrorBoundary
onReset={reset}
fallbackRender={({ resetErrorBoundary }) => (
<div>
<p>There was an error!</p>
<button onClick={() => resetErrorBoundary()}>Try again</button>
</div>
)}
>
{children}
</ErrorBoundary>
)
}Connect the error boundary's reset action to the hook's reset function so failed queries can retry when the boundary is reset.
When to use it
Retry throwOnError failures
Queries use throwOnError to delegate failures to an error boundary while the fallback provides a Try again control.
Integrate an external error boundary
An application uses react-error-boundary and needs its onReset callback to reset TanStack Query errors.
Interview questions
QWhat does useQueryErrorResetBoundary return and how is it used?
It returns a QueryErrorResetBoundaryValue, whose reset function tells TanStack Query that failed queries may retry during the next render. Use that function as the error boundary's reset callback.
Follow-up: How does scope change when a QueryErrorResetBoundary is present? The nearest boundary limits the reset to query errors inside that boundary; without one, the reset is global.
QHow does the hook interact with QueryErrorResetBoundary?
The hook resets query errors within the closest QueryErrorResetBoundary. It is useful when an external error-boundary component, such as react-error-boundary, needs to coordinate its reset with TanStack Query.
Follow-up: Why is coordinating both resets necessary? The UI error boundary must clear its displayed error while TanStack Query must also clear its query-error state so rendering can retry.
QHow would you wire a retry button to this hook?
Use the returned reset function as the error boundary's onReset callback. A retry button can then invoke the boundary's resetErrorBoundary function, which calls the TanStack Query reset callback.
Follow-up: What query configurations commonly require this pattern? It is especially relevant when queries use suspense or throwOnError, because rendering can surface query failures to an error boundary.
Related
QueryErrorResetBoundaryQueryErrorResetBoundaryValuesuspensethrowOnError