useInfiniteQuery: fetchNextPage cancels all refetches, including those triggered by cache invalidation

[LeshaTat]

Describe the bug

When using fetchNextPage with the cancelRefetch: true option (which is the default), all refetching, including refetching after cache invalidation, is canceled. The documentation explicitly states that with this option enabled, fetchNextPage will cancel the previous invocations, not every refetch attempt. This leads to hard-to-debug errors where server requests are correctly executed, but the cache doesn't update.

Real-life Example

In React Native, you put lists into FlatList that has an onEndReached property. When you specify onEndReached={()=>fetchNextPage}, and if the list is short, this request starts immediately after mounting the list and prevents refetching if the data was loaded before.

Your minimal, reproducible example

https://codesandbox.io/p/sandbox/modern-lake-yslmds?file=%2Fsrc%2FApp.js%3A1%2C24

Steps to reproduce

1. Hide the list by clicking on "Toggle".
2. Click "Invalidate".
3. Untoggle the list back.

Expected behavior

The list should update.

How often does this bug happen?

Every time

Screenshots or Videos

No response

Platform

React Native

Tanstack Query adapter

react-query

TanStack Query version

v5.0.0-beta.20

TypeScript version

No response

Additional context

The issue also appears in previous versions of React Query.

[TkDodo]

When using fetchNextPage with the cancelRefetch: true option (which is the default), all refetching, including refetching after cache invalidation, is canceled.

yes, this is on purpose. the problem is: you can only have one fetch running per infinite query. if you run a refetch (because of invalidation), you can't fetch the next page. If you fetch the next page, you can't refetch (you'll also get no window focus refetch when fetching the next page etc.)

The thing is, both invalidation (queryClient.invalidateQueries()) and fetching the next page (fetchNextPage()) are imperative calls where you have the option to make them or not make them. With infinite queries, if you don't want to trigger a fetchNextPage, you can put it behind a guard:

if (!isFetching) {
  fetchNextPage()
}

We've set cancelRefetch to true for those imperative invocations because it's usually what you want. If a developer calls a function, you'd expect it to do something. This is especially important when using invalidation after consecutive mutations - you'd want the last call to yield the latest results, not pick up the running promise of a long-running invalidation from some time ago.

I think we should maybe document the behaviour better and/or rename the cancelRefetch flag to something else, because it no only cancels refetches, it cancels all currently running fetches and makes sure that your fetch succeeds. Maybe it should be force: true or soft: false or something ?

[LeshaTat]

Thanks @TkDodo! Your approach using "isFetching" as a guard seems perfectly fine to me.

I think the "cancelRefetch" option name is clear enough. However, I believe there should be an explicit warning in the documentation about potential side effects, perhaps in multiple places (i.e., not only in the infinite query description, but also in important defaults and maybe elsewhere). I've encountered this issue twice: first on my own, and then while trying to help my colleague. I feel like this could be quite common.

There's something that still bothers me. The issue isn't just about a collision between two imperative calls. This behaviour also prevents "refetchOnMount" from updating stale data. I don't know how it works internally, but it seems that after canceling the refetch request or completing the fetch for the next page, the stale data is marked as fresh, which I find counterintuitive. However, it may indeed be correct; it seems legit that an imperative action could cancel declarative behaviour.

[TkDodo]

it seems legit that an imperative action could cancel declarative behaviour.

yes, that's the intention.

This behaviour also prevents "refetchOnMount" from updating stale data. I don't know how it works internally, but it seems that after canceling the refetch request or completing the fetch for the next page, the stale data is marked as fresh, which I find counterintuitive.

So, lets put it like that:

• if a fetch is currently going on (for whatever reason), and you trigger another refetch imperatively, the imperative one takes precedence, meaning it will cancel the currently running one and trigger a new one (unless you pass cancelRefetch: false)
• if a fetch is currently going on (for whatever reason), and you would get an automatic refetch, e.g. because you focus the window or because a new component mounts, they would just be ignored ("deduplicated") and the previous call would continue.
• if a fetch finishes successfully, the dataUpdatedAt timestamp will be updated, which means data will be seen as fresh for as long as staleTime hasn't elapsed. This is directly tied to the dataUpdatedAt timestamp, so setting this will reset the timer.

If you see a different behaviour, please let me know. If that's still counterintuitive, we need to explain it better 😅 .

Also, feel free to add a PR to the docs. I think it should still stay on the infinite query guide page, because its mostly specific to infinite queries.

[LeshaTat]

I've noticed that even when using the isFetching condition, there are inconsistencies. For instance, if you set the staleTime to one minute and re-enter the screen within that time, a refetch will never occur. This is because fetchNextPage does indeed reset dataUpdatedAt. This problem exists whether you use the isFetching approach or cancelRefetch. This particular problem can be solved by conditioning on hasNextPage rather than on isFetching, but this approach has its own drawbacks.

• if a fetch finishes successfully, the dataUpdatedAt timestamp will be updated, which means data will be seen as fresh for as long as staleTime hasn't elapsed. This is directly tied to the dataUpdatedAt timestamp, so setting this will reset the timer.

The thing is that fetchNextPage doesn't fully update the data; it only loads a part of it. However, dataUpdatedAt is still updated, which I find a bit misleading.

Ideally, one should manually create an onEndReached-like callback that is triggered only by user action. In its absence, what's the best trade-off?

[TkDodo]

The thing is that fetchNextPage doesn't fully update the data; it only loads a part of it. However, dataUpdatedAt is still updated, which I find a bit misleading.

That's an architectural "problem": There is only one cache entry for the whole infinite query, and it consists of multiple pages, being produced by multiple fetches (calls of the queryFn). The dataUpdatedAt timestamp shows the last time data was changed, which is true for refetches, but also if you append a new page to data via fetchNextPage.

I think you just want to check for hasNextPage && !isFetching. This is also what we are doing in the examples:

query/examples/react/load-more-infinite-scroll/src/pages/index.js

Lines 92 to 96 in 3aa0680

	<button
	ref={ref}
	onClick={() => fetchNextPage()}
	disabled={!hasNextPage || isFetchingNextPage}
	>

[TkDodo]

I don't see any tangible actions for us to take here. If you think we can improve the docs, please open a PR.