Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

invalidateQueries or refetch does nothing in React Query and React Native

ErrorinvalidateQueries does not refetch

Short answer

invalidateQueries only refetches queries whose key starts with the key you pass and that are in use. It does nothing for a disabled query, and a key that differs by one element matches nothing. After a mutation, return the invalidation promise. On React Native, screen focus does not refetch unless you wire it.

  • Applies to TanStack Query v5, React Native 0.76+
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the key you invalidate with the key used in useQuery. Log the cache keys and see which queries exist and their state.

    const qc = useQueryClient();
    console.log(qc.getQueryCache().getAll().map(q => [q.queryKey, q.state.status]));
  2. 2Match what you see, then jump to its fix

    1. 1The cache log shows a key like ['todos', { page: 1 }] while you invalidate ['todo'] or ['todos', 1].The key you invalidate does not match the key you queryFix
    2. 2The log shows the query as disabled, and neither invalidateQueries nor refetchQueries does anything.The query is disabled with enabled: falseFix
    3. 3The list updates a moment late, or the button spinner stops before fresh data arrives.The invalidation runs outside the mutation flowFix
    4. 4Going back to a screen shows old data until you pull to refresh.React Native does not refetch on screen or app focus by itselfFix

What does the error look like?

  • invalidateQueries does not refetch
  • data does not update after mutation
  • refetchQueries has no effect

Cause 1 of 4

The key you invalidate does not match the key you query

1Check

Matching is by prefix on array elements. Array order matters, so ['todos', status, page] and ['todos', page, status] are different keys.

grep -n "queryKey" -r src/

2Fix

Use one key shape everywhere and invalidate the shared prefix. Add exact: true only when you want an exact match.

useQuery({ queryKey: ['todos', { page }], queryFn: fetchTodos });

queryClient.invalidateQueries({ queryKey: ['todos'] });

3Verify

Run the mutation and watch the network request for the list fire again.

# network tab or React Query devtools shows the query as fetching

Confirmed by tanstack.com

Did this fix it?

Cause 2 of 4

The query is disabled with enabled: false

1Check

A disabled query ignores invalidateQueries and refetchQueries calls that would normally refetch it.

grep -n "enabled:" -r src/

2Fix

Enable the query once its inputs exist, or call the refetch function returned by useQuery to fetch it manually.

const { data, refetch } = useQuery({
  queryKey: ['user', id],
  queryFn: () => fetchUser(id),
  enabled: !!id,
});
// manual: refetch();

3Verify

Set the input and confirm a request goes out.

# network tab shows the request

Confirmed by tanstack.com

Did this fix it?

Cause 3 of 4

The invalidation runs outside the mutation flow

1Check

Look for invalidateQueries called without return inside onSuccess, or called before the mutation has succeeded.

grep -n -B2 -A6 "useMutation" -r src/

2Fix

Call invalidateQueries in onSuccess and return its promise, so the mutation stays pending until the refetch finishes.

const mutation = useMutation({
  mutationFn: addTodo,
  onSuccess: () =>
    queryClient.invalidateQueries({ queryKey: ['todos'] }),
});

3Verify

The pending state of the mutation ends only after the list shows the new item.

# mutation.isPending stays true until the refetch completes

Confirmed by tanstack.com

Did this fix it?

Cause 4 of 4

React Native does not refetch on screen or app focus by itself

1Check

React Native has no window focus events, so focus refetching needs focusManager with AppState for app focus and useFocusEffect for screen focus.

grep -n "focusManager\|useFocusEffect" -r src/

2Fix

Connect AppState to focusManager, and refetch stale active queries when a screen regains focus.

import { AppState, Platform } from 'react-native';
import { focusManager } from '@tanstack/react-query';

AppState.addEventListener('change', (status) => {
  if (Platform.OS !== 'web') focusManager.setFocused(status === 'active');
});

3Verify

Send the app to the background, change data on the server, return to the app: the query refetches if it is stale.

# set a short staleTime while testing

Confirmed by tanstack.com

Did this fix it?

How do I stop it coming back?

  • Put every variable the query function uses in the query key.
  • Define key builders in one file so invalidation uses the same shape.
  • Return the invalidation promise from mutation callbacks.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

Expo app never leaves the splash screen

App shows the splash screen forever and no error appears

After SplashScreen.preventAutoHideAsync() the splash stays until you hide it yourself.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.