Open History to see the last commit
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>
63}
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.