docs: make the incompatibility of `skipToken` and `refetch` more detailed

[gomesalexandre]

Describe the bug

First of all, thanks for skipToken Janeek and TkDodo 💜. This made useQuery()a lot more enjoyable to use with TS, without a bunch of non-null assertions (which we would always inevitably get wrong by missing some).

While in the process of migrating all our calls to it from enabled, had some tedious time spotting the root cause of this Missing queryFn error:

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

Lines 393 to 396 in bda8a54

	if (!options.queryFn || options.queryFn === skipToken) {
	return () =>
	Promise.reject(new Error(`Missing queryFn: '${options.queryHash}'`))
	}

Eventually figured it out, and it was a legacy refetch() call which was still present after the migration. While this was specified in docs, I believe there could be more details as far as what "doesn't work" means, either in terms of docs of error messaging:

query/docs/framework/react/guides/disabling-queries.md

Line 15 in bda8a54

- `refetch` returned from `useQuery` can be used to manually trigger the query to fetch. However, it will not work with `skipToken`.

Not sure to which extent we would like to document the docs (i.e whether or not we would like to go into full details that refetch() will mount an observer and that there can't be an observer without an actual queryFn()), but as a developer using skipToken, I believe there would be good value in at least documenting the aforementioned behaviour, or even better, improve the checks and messaging of the error to reflect the cause.

Your minimal, reproducible example

https://codesandbox.io/p/sandbox/great-snyder-t5vxyk?file=/src/App.js

Steps to reproduce

• Have a useQuery() call with skipToken
• Try and call the imperative refetch() method for that query
• Notice the query is in errored state (Missing queryFn: <hash>) until queryFn actually becomes a function.

Expected behavior

Either/or:

• Docs clearly mention that refetch() will eventually result in a Missing queryFn error
• Checks are made for refetches explicitly, and the messaging of the error is improved e.g Cannot call refetch() with skipToken

How often does this bug happen?

None

Screenshots or Videos

N/A

Platform

N/A

Tanstack Query adapter

react-query

TanStack Query version

5

TypeScript version

No response

Additional context

No response

[TkDodo]

Docs clearly mention that refetch() will eventually result in a Missing queryFn error

please file a PR to the docs

Checks are made for refetches explicitly, and the messaging of the error is improved e.g Cannot call refetch() with skipToken

We don't know if a fetch was made by a call to refetch() or not, but we can definitely change the message if the queryFn was a skipToken to hint that the most likely way this can happen is if you called refetch() while the queryFn was set to skipToken.

[tychenjiajun]

Personally I think skipToken should also skip refetch and return undefined instantly, not to throw any error.

Or can we throw error only in development and silently ignore it in production?