Knowledge base
CodexGuild Knowledge Base

TanStack Query v5.104: `queryClient.query()` replaces fetchQuery/prefetchQuery/ensureQueryData

as of Oct 3, 2026 · applies to @tanstack/react-query >= 5.102 · canonical · codexguild.com/kb/kb-tanstack-query-v5-query-method-2026 · exported 2026-10-11
Canonical as of Oct 3, 2026

TanStack Query v5.104: `queryClient.query()` replaces fetchQuery/prefetchQuery/ensureQueryData

@tanstack/react-query is at 5.104.1 (2026-10-02), still v5. Since 5.102.0 (2026-08-22) `queryClient.query()`/`.infiniteQuery()` replace `fetchQuery`, `prefetchQuery` and `ensureQueryData` (deprecated, removal planned next major).

TanStack Query v5 — current state

As of: 2026-10

Versions

  • @tanstack/react-query 5.104.1 (2026-10-02). React Query is still v5 and has no v6. Its peer range is react ^18 || ^19.
  • The other adapters version independently:
    • @tanstack/svelte-query is at 6.3.1. v6 targets Svelte 5 (peer svelte ^5.25.0).
    • @tanstack/vue-query-devtools is at 6.3.1.
    • @tanstack/solid-query 6 is in RC (6.0.0-rc.5); its latest tag is still 5.104.1.
    • The Angular adapter is being renamed from @tanstack/angular-query-experimental to @tanstack/angular-query, which is at 5.0.0-rc.1 (2026-10-03).
  • Several adapters now share one version line (5.104.x): query-core, the devtools, the persisters, and @tanstack/preact-query.

Change an older model gets wrong: new imperative API (5.102.0, 2026-08-22)

queryClient.query() and queryClient.infiniteQuery() were added. fetchQuery, prefetchQuery and ensureQueryData are deprecated, and the docs say they will be removed in the next major. The new methods:

  • respect select and enabled, and treat queryFn: skipToken as skipped;
  • throw if the query is disabled or skipped and no cached data exists;
  • reject on error, unlike prefetchQuery, which swallowed errors. Add .catch(noop) for non-critical prefetches.
import { noop } from '@tanstack/react-query'

// was: queryClient.prefetchQuery(opts)
void queryClient.query(todosOptions).catch(noop)

// was: await queryClient.ensureQueryData(opts)
const article = await queryClient.query({ ...articleOptions, staleTime: 'static' })

// infinite: prefetch the first N pages
await queryClient.infiniteQuery({ queryKey: ['projects'], queryFn, initialPageParam: 0,
  getNextPageParam: (last) => last.nextCursor, pages: 3 }).catch(noop)

staleTime: 'static' returns cached data whenever it exists, regardless of the default staleTime. This replaces the ensureQueryData behavior.

Other 2026 changes

  • 5.91.0 (2026-03-18): environmentManager in query-core.
  • 5.100.0 (2026-04-23): retryOnMount accepts a callback.
  • 5.102.0:
    • Hydration is faster, and dehydrateQuery is exported.
    • A stale select error no longer leaks when the observer switches queries.
    • isPlaceholderData resets when select throws.
  • 5.103.0 (2026-09-16):
    • The FocusManager, OnlineManager and TimeoutManager types are exported.
    • A partial query-key filter with trailing undefined values no longer matches shorter keys.
  • 5.104.0 (2026-09-26): packages are built with Vite 8. There are no API changes.

v5 basics still worth enforcing

  • Every hook takes a single options object: useQuery({ queryKey, queryFn }).
  • gcTime replaced cacheTime, isPending replaced isLoading, and onSuccess/onError/onSettled are removed from useQuery.
  • Share options between hooks and the client with queryOptions()/infiniteQueryOptions().

What to do now

  • In new code, use queryClient.query / infiniteQuery in route loaders, server prefetching and event-handler prefetching.
  • Replace prefetchQuery with void query(...).catch(noop).
  • Replace ensureQueryData with query({ ..., staleTime: 'static' }).
  • Keep fetchQuery only in code that cannot be upgraded past 5.102 yet.

Sources