web/.agents/skills/tanstack-query-best-practices/rules/err-error-boundaries.md
When using Suspense with TanStack Query, errors propagate to error boundaries. Use useQueryErrorResetBoundary to reset query errors when users retry, preventing stuck error states.
// Error boundary without query reset - retry may not work
function ErrorBoundary({ children }: { children: React.ReactNode }) {
return (
<ReactErrorBoundary
fallbackRender={({ error, resetErrorBoundary }) => (
<div>
<p>Error: {error.message}</p>
<button onClick={resetErrorBoundary}>Try again</button>
</div>
)}
>
{children}
</ReactErrorBoundary>
)
}
// Query error persists after retry click
import { useQueryErrorResetBoundary } from '@tanstack/react-query'
import { ErrorBoundary } from 'react-error-boundary'
function QueryErrorBoundary({ children }: { children: React.ReactNode }) {
const { reset } = useQueryErrorResetBoundary()
return (
<ErrorBoundary
onReset={reset}
fallbackRender={({ error, resetErrorBoundary }) => (
<div className="error-container">
<h2>Something went wrong</h2>
<pre>{error.message}</pre>
<button onClick={resetErrorBoundary}>
Try again
</button>
</div>
)}
>
{children}
</ErrorBoundary>
)
}
// Usage with Suspense
function App() {
return (
<QueryErrorBoundary>
<Suspense fallback={<Loading />}>
<Posts />
</Suspense>
</QueryErrorBoundary>
)
}
function Posts() {
// useSuspenseQuery throws on error, caught by boundary
const { data } = useSuspenseQuery({
queryKey: ['posts'],
queryFn: fetchPosts,
})
return <PostList posts={data} />
}
// Route-level error handling
import { createFileRoute } from '@tanstack/react-router'
import { useQueryErrorResetBoundary } from '@tanstack/react-query'
export const Route = createFileRoute('/posts')({
loader: ({ context: { queryClient } }) =>
queryClient.ensureQueryData(postQueries.list()),
errorComponent: ({ error, reset }) => {
const { reset: resetQuery } = useQueryErrorResetBoundary()
return (
<div>
<p>Failed to load posts: {error.message}</p>
<button
onClick={() => {
resetQuery()
reset()
}}
>
Retry
</button>
</div>
)
},
component: PostsPage,
})
// Granular error boundaries for isolated failures
function Dashboard() {
return (
<div className="dashboard">
<QueryErrorBoundary>
<Suspense fallback={<Skeleton />}>
<RecentActivity />
</Suspense>
</QueryErrorBoundary>
<QueryErrorBoundary>
<Suspense fallback={<Skeleton />}>
<Statistics />
</Suspense>
</QueryErrorBoundary>
<QueryErrorBoundary>
<Suspense fallback={<Skeleton />}>
<Notifications />
</Suspense>
</QueryErrorBoundary>
</div>
)
}
useQueryErrorResetBoundary clears error state for all queries in the boundary