Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

query-retries.md

105 lines3.5 KB

1---
2id: query-retries
3title: Query Retries
4---
5​
6When a `useQuery` query fails (the query function throws an error), TanStack Query will automatically retry the query if that query's request has not reached the max number of consecutive retries (defaults to `3`) or a function is provided to determine if a retry is allowed.
7​
8You can configure retries both on a global level and an individual query level.
9​
10- Setting `retry = false` will disable retries.
11- Setting `retry = 6` will retry failing requests 6 times before showing the final error thrown by the function.
12- Setting `retry = true` will infinitely retry failing requests.
13- Setting `retry = (failureCount, error) => ...` allows for custom logic based on why the request failed. Note that `failureCount` starts at `0` for the first retry attempt.
14​
15[//]: # 'Info'
16​
17> On the server, retries default to `0` to make server rendering as fast as possible.
18​
19[//]: # 'Info'
20[//]: # 'Example'
21​
22```tsx
23import { useQuery } from '@tanstack/react-query'
24​
25// Make a specific query retry a certain number of times
26const result = useQuery({
27 queryKey: ['todos', 1],
28 queryFn: fetchTodoListPage,
29 retry: 10, // Will retry failed requests 10 times before displaying an error
30})
31```
32​
33[//]: # 'Example'
34​
35> Info: Contents of the `error` property will be part of `failureReason` response property of `useQuery` until the last retry attempt. So in above example any error contents will be part of `failureReason` property for first 9 retry attempts (Overall 10 attempts) and finally they will be part of `error` after last attempt if error persists after all retry attempts.
36​
37## Retry Delay
38​
39By default, retries in TanStack Query do not happen immediately after a request fails. As is standard, a back-off delay is gradually applied to each retry attempt.
40​
41The default `retryDelay` is set to double (starting at `1000`ms) with each attempt, but not exceed 30 seconds:
42​
43[//]: # 'Example2'
44​
45```tsx
46// Configure for all queries
47import {
48 QueryCache,
49 QueryClient,
50 QueryClientProvider,
51} from '@tanstack/react-query'
52​
53const queryClient = new QueryClient({
54 defaultOptions: {
55 queries: {
56 retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
57 },
58 },
59})
60​
61function App() {
62 return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
64```
65​
66[//]: # 'Example2'
67​
68Though it is not recommended, you can obviously override the `retryDelay` function/integer in both the Provider and individual query options. If set to an integer instead of a function the delay will always be the same amount of time:
69​
70[//]: # 'Example3'
71​
72```tsx
73const result = useQuery({
74 queryKey: ['todos'],
75 queryFn: fetchTodoList,
76 retryDelay: 1000, // Will always wait 1000ms to retry, regardless of how many retries
77})
78```
79​
80[//]: # 'Example3'
81​
82## Background Retry Behavior
83​
84When using `refetchInterval` with `refetchIntervalInBackground: true`, retries will pause when the browser tab is inactive. This happens because retries respect the same focus behavior as regular refetches.
85​
86If you need continuous retries in the background, consider disabling retries and implementing a custom refetch strategy:
87​
88[//]: # 'Example4'
89​
90```tsx
91const result = useQuery({
92 queryKey: ['todos'],
93 queryFn: fetchTodos,
94 refetchInterval: (query) => {
95 // Refetch more frequently when in error state
96 return query.state.status === 'error' ? 5000 : 30000
97 },
98 refetchIntervalInBackground: true,
99 retry: false, // Disable built-in retries
100})
101```
102​
103[//]: # 'Example4'
104​
105This approach lets you control retry timing manually while keeping refetches active in the background.