HydrationBoundary double fetching on subsequent visits

[CB2Moon]

Describe the bug

I used HydrationBoundary in React Router. In loader(), I get the data, dehydrate it, then hydrate the client side query client.

1. For the first visit, since it's a new query, it got hydrated in React.useMemo
2. For subsequent visits, it will be deferred to React.useEffect, however, if the cache is stale, query client will refetch before useEffect, which makes the server compute the data twice: one in loader, the other in the component

I looked into the source code and found that it's due to refetchOnMount, which is true by default. I think it would be plausible to prevent a refetch if the query in the dehydrated state is fresh.

There are some experiments in the provided code, e.g. initialData from React Query meets React Router, initialData + initialDataUpdatedAt, HydrationBoundary, and my custom hook use-hydrated-query which sets refetchOnMount to false for that query if not explicitly provided during hydration. You may navigate away and back for each experiment and see the log in console to reproduce the issue.

Your minimal, reproducible example

https://stackblitz.com/edit/vitejs-vite-yiggax3s

Steps to reproduce

mentioned in 'Describe the bug'

Expected behavior

If query is fresh from loader(), client side query client should not refetch

How often does this bug happen?

Every time

Screenshots or Videos

No response

Platform

Any browser

Tanstack Query adapter

react-query

TanStack Query version

v5.85.3

TypeScript version

5.8.3

Additional context

No response

[TkDodo]

@Ephem could you have a look at this please?

[joseph0926]

In my opinion, this issue seems to be a case where React's rendering order conflicts with React Query's behavior.

The reason HydrationBoundary delays existing queries with useEffect is likely to prevent unexpected UI updates during React's Concurrent rendering.
The problem is that this causes a side effect (this issue)

useMemo (during render) → component render → useEffect (after render)
During this window, useQuery executes, detects a “stale cache,” and initiates a refetch.

To fix this issue, I believed we needed to prevent unnecessary refetches while maintaining transition safety.

Therefore, I passed a flag indicating “this query is about to be hydrated with fresh data,” instructing the QueryObserver to wait briefly. Of course, since it still runs in useEffect during the transition, safety is maintained.

[Ephem]

Sorry for the delay before looking at this, I've had a few busy weeks.

I think your analysis about what is happening is likely correct, but the details are tricky to reason about here. I think the HydrationBoundary useEffect should always run before useBaseQuery effects further down the tree, so if we have hydrated something, it should already be in the cache when the next effect runs. However, because these effects happen in the same pass, I suspect useSyncExternalStore has not had time to update, which might be an important detail here.

I haven't verified the exact behaviour so not sure about the best fix yet, thank you for reporting this!