Suspense query is retried infinitely with low gcTime

[foxable]

Describe the bug

I'm using useSuspenseQuery with retry: false and a low gcTime (started with 0, but the same problem can be observed for gcTimes which are generally lower than 1s. When the query throws an error, it is retried infinitely, or at least multiple times with a low gcTime which is not 0.

Your minimal, reproducible example

https://github.com/foxable/reproduction-react-query-suspense-infinite-retry/tree/main

Steps to reproduce

1. Run npm run dev
2. Open http://localhost:3000/

Expected behavior

I expected the query to run only once on both the server and the client, but on the client it is retried infinitely (the same happens on the server when setting gcTime: 0.

Setting retryOnMount: false does not change this behavior.

How often does this bug happen?

Every time

Screenshots or Videos

No response

Platform

• OS: Linux
• Browser: Firefox, Chrome

Tanstack Query adapter

react-query

TanStack Query version

v5.51.21

TypeScript version

v5.5.4

Additional context

No response

[TkDodo]

This seems to be tied to nextJs and how / when they render an error.tsx file. The same code works fine in vite:

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

It also seems to work better if we use a custom ErrorBoundary in nextJs:

https://stackblitz.com/edit/github-j7jvy1?file=src%2Fapp%2Fpage.tsx,src%2Fapp%2Flayout.tsx,src%2Fapp%2Ferror.tsx

so it seems to be an upstream problem with nextJs to me? My best guess is that the Home component keeps rendering even though the error.tsx component should render and that makes the query suspend all over again?

But also, please note that using suspense in nextJs means you likely should opt into hydration, either with HydrationBoundary or with our experimental next-streaming package. Otherwise, the fetch will run on the server, but the data won't make it into the client cache, so you'd just fetch right on the client again. That likely isn't what you want.

[foxable]

Thank you very much for your reply. Actually, I already use a custom ErrorBoundary in some parts of the original application. At least in Next.js, I could observe the issue for both the custom ErrorBoundary as well as the error.tsx.

Did you try your Vite sample with gcTime: 0? Because then I can reproduce the issue even with Vite. As far as I could check, the issue is flaky when using a low gcTime which is above 0.

My original intention was to use gcTime: 0 to force the Suspense fallback whenever navigating back to the page containing useSuspenseQuery. The low gcTime > 0 was mostly a try to work around the issue, but came with the mentioned flakiness.

Regarding hydration, I explicitly did not configure it because in the original application, there is a reverse proxy in front of Next.js which requires me to send all requests from the browser (they simply won't succeed on the server). To achieve this, I throw an error on the server to opt out of rendering on the server, so there will never actually be data from the server.

[TkDodo]

Did you try your Vite sample with gcTime: 0? Because then I can reproduce the issue even with Vite. As far as I could check, the issue is flaky when using a low gcTime which is above 0.

sorry, I didn't see that I copied gcTime: 10, I thought it was zero. I updated my vite sandbox and ideed, there is an infinite querying now. Things work with gcTime: 1.

I think I know why that is: For "reasons", react renders components that have already thrown to error boundaries once more even after they have thrown. It shouldn't matter, because components need to be idempotent. In this case though, it matters because with gcTime: 0, we immediately remove it from the cache without setting a timeout.

what we can try is scheduling a timer as well for when gcTime is zero. That might just be enough. Let me try that.

[TkDodo]

this doesn't work and it seems like there is no good solution to this problem. The only thing I can offer is to set gcTime to at least 1 second when suspense is enabled. We do the same thing for staleTime. I wrote a test that fails without the workaround, and it passes with it. Would that work for you? Please see the attached PR:

• fix(react-query): ensure we have a gcTime of at least 1 second when using suspense #7860

[foxable]

I just tested it, and after your change the error boundary is now triggered reliably without any retries.

Having a low gcTime > 0 is fine to me, because I can still achieve the desired behavior. Before, it was just impossible to find a gcTime which is high enough to always trigger the ErrorBoundary, but low enough to garbage-collect query results immediately (more or less).

So, thank you very much for your help and the quick fix!

I'm not sure if I should close this issue already, at least from my point of view the issue is fixed. So I leave it up to you to decide when to close this issue.