Transient network recovery
A flaky network request should recover without immediately displaying an error.
TanStack · Pipe
retry
The retry option controls whether failed TanStack Query requests run again. It supports a retry count, disabling or infinite retries, and a callback for error-aware decisions.
How it works
The retry option controls whether a failed query runs again. It accepts a retry count, false to disable retries, true for unlimited retries, or a function that decides from the failure count and error; client defaults are three retries, while server defaults are zero.
Syntax
retry: number | false | true | ((failureCount: number, error: TError) => boolean)Parameters
| Name | Type | Description |
|---|---|---|
retry | number | false | true | ((failureCount: number, error: TError) => boolean) | Maximum retry count, false to disable retries, true for infinite retries, or a predicate receiving failureCount and error. |
Key points
- A thrown query-function error triggers automatic retries until the configured policy stops them.
- Retry behavior can be set globally or overridden for a specific query.
- Use false when a failed request must immediately reach the error state.
- A numeric value sets the maximum number of retry attempts before the final error is shown.
- true enables unbounded retries, so it should be reserved for cases where that behavior is intentional.
- A callback can choose retry behavior using both the number of failures and the error.
Common mistakes
- A custom retry function must account for zero-based failureCount when limiting attempts.
Example: Custom retry policy
import { useQuery } from '@tanstack/react-query'
export function Todos() {
const query = useQuery({
queryKey: ['todos'],
queryFn: async () => {
const response = await fetch('/api/todos')
if (!response.ok) throw new Error('Request failed')
return response.json()
},
retry: (failureCount, error) => {
if (error instanceof Error && error.message === 'Request failed') {
return failureCount < 2
}
return false
},
})
return <pre>{JSON.stringify(query.data ?? null)}</pre>
}The query retries only twice for this error, then exposes the final failure.
When to use it
Error-aware retry policy
Only selected errors should be retried while permanent failures stop immediately.
Client and server configuration
Different environments need different latency and resilience trade-offs.
Interview questions
QWhat forms can the retry option take?
retry may be false, true, a number, or a function receiving failureCount and error. false prevents retries, true retries indefinitely, a number limits retries, and the function returns whether another attempt is allowed.
Follow-up: How would you avoid retrying authentication failures? Return false from the function when the error represents an authentication failure, and retry only transient failures.
QWhat are the default retry counts?
The client default is three retries, but server rendering defaults to zero. This avoids making server-side rendering wait through retry attempts unless the application explicitly opts in.
Follow-up: Why might a server application configure retries explicitly? It may need resilience for transient upstream failures, while accepting the added rendering latency.
QHow should a retry callback limit attempts?
The retry callback receives the current failureCount and the thrown error. Because the first retry attempt has a count of zero, a condition such as failureCount < 2 permits two retry attempts.
Follow-up: How can retry timing be customized? Configure retryDelay with a number or function; a function can implement linear or exponential backoff.
Related
retryDelayuseQueryQueryClientQueryOptions