Query with cancellation breaks when used with `useQuery` and `fetchQuery` simultaneously under StrictMode

[longzheng]

Describe the bug

UPDATE: since the issue was initially created I've ruled out the useSuspenseQuery, it seems to be caused by the unmount behaviour of StrictMode and useQuery. #9440 (comment)

A single query with cancellation support that is used as both a useQuery suspense query useSuspenseQuery and a manually invoked query queryClient.fetchQuery, after the StrictMode double render, the fetchQuery promise never return, leading to an unexpected inability to fetch API data.

For example this query which consumes the queryFn signal and passes it to fetch

const query = queryOptions({
  queryKey: ['repoData'],
  queryFn: async ({ signal }) => {
    const response = await fetch(
      'https://api.github.com/repos/TanStack/query',
      { signal }
    );
    return await response.json();
  },
});

When used in a component with both useSuspenseQuery and queryClient.fetchQuery

function Example() {
  const { data: suspenseData } = useSuspenseQuery(query);
  console.log('suspense data', suspenseData);

  const { isPending, error, data, isFetching } = useQuery({
    queryKey: ['test'],
    queryFn: async () => {
      const result = await queryClient.fetchQuery(query);
      console.log('queryFn data', data);

      return result;
    },
  });

the await queryClient.fetchQuery() will never return, and thus the useQuery is stuck pending forever.

Note I've disabled automatic retry to make this problem more obvious, otherwise the retry behaviour would workaround it.

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: false,
      refetchOnWindowFocus: false,
    },
  },
});

This problem appears is easily reproducible with <StrictMode> because of the double rendering that appears to be causing the abort signal. I'm not sure if there is another scenario where the query is also aborted leading to this error.

Your minimal, reproducible example

https://stackblitz.com/edit/tanstack-query-qjpbgwfe?file=src%2Findex.tsx&preset=node

Steps to reproduce

1. Open the page
2. See "Loading..." state
3. fetchQuery does not return promise
4. Open DevTools, suspense data is logged but queryFn data is not logged

Expected behavior

1. Open the page
2. See data rendered
3. fetchQuery returns promise
4. Open DevTools, suspense data and queryFn data are both logged

How often does this bug happen?

Every time

Screenshots or Videos

Screen.Recording.2025-07-16.223228.mp4

Platform

• OS: Windows
• Chrome 138

Tanstack Query adapter

react-query

TanStack Query version

5.83.0

TypeScript version

5.8.3

Additional context

I noticed on the query cancellation documentation page it says

Cancellation does not work when working with Suspense hooks: useSuspenseQuery, useSuspenseQueries and useSuspenseInfiniteQuery.
However I interpret this to mean that useSuspenseQuery will not respect cancellations, not that it will break entirely.

This issue may be related to #7889 and #8060

[TkDodo]

it’s documented that cancelation doesn’t work with suspense:

• https://tanstack.com/query/latest/docs/framework/react/guides/query-cancellation#limitations

[TkDodo]

also note that this has nothing to do with fetchQuery. Your second query with the key ['test'] doesn't even start to run, because useSuspenseQuery will unmount the query. You can check in the devtools that the ['test'] query is in fetchStatus: 'idle'.

[longzheng]

also note that this has nothing to do with fetchQuery. Your second query with the key ['test'] doesn't even start to run, because useSuspenseQuery will unmount the query. You can check in the devtools that the ['test'] query is in fetchStatus: 'idle'.

Sorry do you mean it doesn't run on the second render due to StrictMode? I'm seeing the queryFn run once if I put a console log before the fetchQuery.

function Example() {
  console.log('before suspense data')
  const { data: suspenseData } = useSuspenseQuery(query);
  console.log('suspense data', suspenseData);

  const { isPending, error, data, isFetching } = useQuery({
    queryKey: ['test'],
    queryFn: async () => {
      console.log('before fetchQuery')
      const result = await queryClient.fetchQuery(query);
      console.log('queryFn data', data);

      return result;
    },
  });

The console logs are pretty messy but there's one instances of the before fetchQuery

before suspense data
before suspense data
before suspense data
suspense data {id: 207645083, node_id: 'MDEwOlJlcG9zaXRvcnkyMDc2NDUwODM=', name: 'query', full_name: 'TanStack/query', private: false, …}
before suspense data
suspense data {id: 207645083, node_id: 'MDEwOlJlcG9zaXRvcnkyMDc2NDUwODM=', name: 'query', full_name: 'TanStack/query', private: false, …}
before fetchQuery
before suspense data
suspense data {id: 207645083, node_id: 'MDEwOlJlcG9zaXRvcnkyMDc2NDUwODM=', name: 'query', full_name: 'TanStack/query', private: false, …}
before suspense data
suspense data {id: 207645083, node_id: 'MDEwOlJlcG9zaXRvcnkyMDc2NDUwODM=', name: 'query', full_name: 'TanStack/query', private: false, …}
before suspense data
suspense data {id: 207645083, node_id: 'MDEwOlJlcG9zaXRvcnkyMDc2NDUwODM=', name: 'query', full_name: 'TanStack/query', private: false, …}
before suspense data
suspense data {id: 207645083, node_id: 'MDEwOlJlcG9zaXRvcnkyMDc2NDUwODM=', name: 'query', full_name: 'TanStack/query', private: false, …}

[longzheng]

If I add a .catch to the fetchQuery() then I see the CancelledError come through

function Example() {
  const { data: suspenseData } = useSuspenseQuery(query);
  console.log('suspense data', suspenseData);

  const { isPending, error, data, isFetching } = useQuery({
    queryKey: ['test'],
    queryFn: async () => {
      const result = await queryClient.fetchQuery(query).catch((e) => {throw Error(e)});
      console.log('queryFn data', data);

      return result;
    },
  });

[longzheng]

also note that this has nothing to do with fetchQuery. Your second query with the key ['test'] doesn't even start to run, because useSuspenseQuery will unmount the query. You can check in the devtools that the ['test'] query is in fetchStatus: 'idle'.

Actually I think the second query with the key ['test'] fetchStatus is being reset to idle because of the revert state behaviour?

query/packages/query-core/src/query.ts

Lines 626 to 628 in 4d8bbbf

	if (isCancelledError(error) && error.revert && this.#revertState) {
	return { ...this.#revertState, fetchStatus: 'idle' }
	}

[longzheng]

@TkDodo I came up with another repro that doesn't use suspense query but replicates the same issue https://stackblitz.com/edit/tanstack-query-8cywstwk?file=src%2Findex.tsx%3AL57&preset=node

Basically I set up a query, but then invoke it manually with fetchQuery. This causes the original query to now succeed, but the second query is stuck pending.

// set up a query to fetch an API
// with support for query cancellation via abort signal
const query = queryOptions({
  queryKey: ['catFact'],
  queryFn: async ({ signal }) => {
    const response = await fetch('https://catfact.ninja/fact', { signal });
    return await response.json();
  },
});

function Example() {
  // run the original query
  const { data: catFactData, isPending: catFactPending } = useQuery(query);

  // run another query with a different key
  // use fetchQuery to manually invoke the original query
  const { data: testData, isPending: testPending } = useQuery({
    queryKey: ['test'],
    queryFn: async () => {
      const result = await queryClient.fetchQuery(query);
      return result;
    },
  });

However if I remove <StrictMode>, this works correctly and both queries succeed. https://stackblitz.com/edit/tanstack-query-kkkfxsag?file=src%2Findex.tsx&preset=node

ReactDOM.createRoot(rootElement).render(
-  <StrictMode>
    <App />
-  </StrictMode>
);

[longzheng]

This is my best attempt at summarising the situation and what I believe to be the root cause...

With React <StrictMode>, a component will double render, effectively mounts > unmounts > mounts.

TanStack Query automatically cancels queries on component unmount, this is intentional and desirable.

If you make a custom query with a queryFn() consumes the abort signal and passes it to a fetch promise, then the query is immediately cancelled since the fetch promise does not continue to resolve after the component unmounts. For example this query with the key ['catFact']

const query = queryOptions({
  queryKey: ['catFact'],
  queryFn: async ({ signal }) => {
    const response = await fetch('https://catfact.ninja/fact', { signal });
    return await response.json();
  },
});

If the query is used in the component with useQuery then it is effectively started > cancelled > started. For example

function Example() {
  const { data: catFactData, isPending: catFactPending } = useQuery(query);

However if a separate query fetches the first query using queryClient.fetchQuery(), the cancellation of the first query will cause fetchQuery to throw a CancelledError exception.

const { data: testData, isPending: testPending } = useQuery({
  queryKey: ["test"],
  queryFn: async () => {
    const result = await queryClient.fetchQuery(query).catch((e) => {
      console.log(e); // <-- CancelledError
      throw e;
    });
    return result;
  },
});

Whilst the exception itself is not a problem, but the library automatically catches CancelledError inside a query function and reverts the query to its original state and idle.

query/packages/query-core/src/query.ts

Lines 626 to 628 in 4d8bbbf

	if (isCancelledError(error) && error.revert && this.#revertState) {
	return { ...this.#revertState, fetchStatus: 'idle' }
	}

This normally wouldn't be a problem, but because of the StrictMode double render, upon the second render this query never re-runs and is stuck both idling and without any data. (If it did re-run, then the fetchQuery would succeed and data would be returned).

So I believe the root cause is to do with the cancelled error handling behaviour, rather than the cancellation itself.

[Elabar]

Getting same issue here, thought I was going crazy that the query never resolves.
My code is very similar to the reprod here

[TkDodo]

However if a separate query fetches the first query using queryClient.fetchQuery(), the cancellation of the first query will cause fetchQuery to throw a CancelledError exception.

I just fixed that in the latest release. Can you please try it out if it works now - you shouldn’t see a CancelledError again.

see:

• fix(query-core): query cancellation and reverting #9293

this should be in v5.85.2

[longzheng]

However if a separate query fetches the first query using queryClient.fetchQuery(), the cancellation of the first query will cause fetchQuery to throw a CancelledError exception.

I just fixed that in the latest release. Can you please try it out if it works now - you shouldn’t see a CancelledError again.

see:

• fix(query-core): query cancellation and reverting #9293

this should be in v5.85.2

I forked my repro and updated the package "@tanstack/react-query": "^5.85.2" https://stackblitz.com/edit/tanstack-query-3aycsz78?file=package.json,src%2Findex.tsx&preset=node

It seems like the new behaviour now causes both the first query and the second query to be stuck pending with no data on the second render (from StrictMode), which is not what I expected

[TkDodo]

I think this behaviour is still better than before. Queries being stuck in pending state, because the promise to fetchQuery never resolves is really bad.

Right now, what happens is that due to query cancellation, the query gets aborted and reverts back to its initial state (status pending, fetchStatus idle, no data). fetchQuery picks up the same promise, before that one gets cancelled, so after cancellation, they are now both in the same, reverted state, which I think is correct.

So, the two are in sync and this is fine. What’s troubling is that fetching isn’t logged twice. After the unmount aborts and revers the query, the queryFn should run a second time, but it doesn’t.

I could actually reproduce this with just a single query that uses an abort signal - it’s stuck:

https://stackblitz.com/edit/tanstack-query-3wocmzxf?file=src%2Findex.tsx

Going back to 5.85.1 makes this scenario work again so that’s clearly a regression

https://stackblitz.com/edit/tanstack-query-u1v6fyry?file=src%2Findex.tsx

[TkDodo]

I added some tests for strictMode behaviour but they all work as expected. Can’t really explain at the moment why the sandbox behaves that way :/

de3626a

[longzheng]

I added some tests for strictMode behaviour but they all work as expected. Can’t really explain at the moment why the sandbox behaves that way :/

de3626a

Just spitballing, but the signal here isn't quite aborting the query function as a fetch abort would de3626a#diff-d216de90023f217929be4053db0d25b8033d9e5141a70379a0e13896d2f31ddeR1468-R1469

Could you add a signal event listener like the MDN docs

  return new Promise((resolve, reject) => {
    // If the signal is already aborted, immediately throw in order to reject the promise.
    if (signal.aborted) {
      reject(signal.reason);
      return;
    }

    // Perform the main purpose of the API
    // Call resolve(result) when done.

    // Watch for 'abort' signals
    signal.addEventListener("abort", () => {
      // Stop the main operation
      // Reject the promise with the abort reason.
      reject(signal.reason);
    });
  });