TanStack Start throws Cannot read properties of undefined (reading 'mutations') during query hydration on fresh install

[saeid-ebrahimi127]

Which project does this relate to?

Start

Describe the bug

A freshly created TanStack Start application throws the following error in the browser console immediately after running the development server.

Error
Error reading query stream: TypeError: Cannot read properties of undefined (reading 'mutations')
at hydrate (modern-BN-gG8-L.js?v=975f2576:425:18)
at handle (@tanstack_react-router-ssr-query.js?v=73f9cd6e:103:5)

The error occurs immediately after running:

bun run dev

and opening the application in the browser.

Complete minimal reproducer

https://github.com/saeid-ebrahimi127/tanstack-start-project

Steps to Reproduce the Bug

1. Create a new TanStack Start with: tanstack create tanstack-start-project --no-intent --package-manager bun --no-install (tanstack cli)
2. Install the dependencies.
3. Run:
   bun run dev
4. Open the development server in the browser.
5. Check the browser console.

The error appears without adding any custom application logic.

Expected behavior

A newly created TanStack Start application should start successfully without errors in the browser console.

Screenshots or Videos

No response

Platform

OS: [Windows / macOS / Linux]
Bun: 1.4.0
Node: v24.19.0
Vite: 8.2.2
@tanstack/react-start: 1.168.49
@tanstack/react-router: 1.170.32
@tanstack/react-router-ssr-query: 1.167.1
@tanstack/react-query: 5.102.2

Additional context

No response

[saeid-ebrahimi127]

Downgrading @tanstack/react-query from 5.102.2 to 5.101.4 resolves the issue.

With @tanstack/react-query@5.102.2, a fresh TanStack Start project throws:

Error reading query stream: TypeError: Cannot read properties of undefined (reading 'mutations')

during hydration inside @tanstack/react-router-ssr-query.

After changing the dependency to:

"@tanstack/react-query": "5.101.4"

the hydration error no longer occurs and the application runs normally.

It looks like there may be a compatibility issue between @tanstack/react-query@5.102.2 and the current TanStack Start SSR query integration.

[ataschz]

Root cause: the bug is in router-ssr-query-core, not in react-query. The downgrade works by accident.

The stream-reading loop in router-ssr-query-core hydrates before it checks done (packages/router-ssr-query-core/src/index.ts, L194-L207):

reader.read().then(async function handle({ done, value }) {
  queryHydrate(queryClient, value, hydrateOptions)   // ← value is undefined here
  if (done) return                                   // ← too late
  const result = await reader.read()
  return handle(result)
}).catch((err) => console.error('Error reading query stream:', err))

The final reader.read() of any ReadableStream always resolves { done: true, value: undefined }, so queryHydrate is always called once with undefined.

Why it only shows up now. query-core's hydrate() used to take dehydratedState: unknown and early-return on non-objects, which silently absorbed that call. That guard was removed:

- export function hydrate(client, dehydratedState: unknown, options?): void {
-   if (typeof dehydratedState !== 'object' || dehydratedState === null) return
+ export function hydrate(client, dehydratedState: Partial<DehydratedState>, options?): void {
+   const mutationCache = client.getMutationCache()
    ...
    dehydratedState.mutations?.forEach(...)

I bisected the published tarballs — the guard disappears in @tanstack/query-core@5.102.1:

version	guard
5.101.4	✅
5.102.0	✅
5.102.1	❌
5.102.2	❌

So the latent ordering bug has always been there; 5.102.1 just stopped hiding it. Downgrading react-query re-hides it rather than fixing it.

Severity: cosmetic. Every real chunk is hydrated — only the terminal read throws, and it carries no data. But it's a red console error on every page load of every TanStack Start app.

Fix — move the done check above the hydrate call:

  .then(async function handle({ done, value }) {
-   queryHydrate(queryClient, value, hydrateOptions)
-   if (done) return
+   if (done) return
+   queryHydrate(queryClient, value, hydrateOptions)
    const result = await reader.read()
    return handle(result)
  })

Happy to open a PR if that's useful.

Workaround without downgrading, for anyone who needs to stay on the current react-query: wrap the queryStream you hand to the integration so the terminal read yields an empty state instead of undefined. Hydrating { mutations: [], queries: [] } is a no-op, so the if (done) return then exits cleanly — and it self-neutralises once this is fixed upstream.

[saeid-ebrahimi127]

Root cause: the bug is in router-ssr-query-core, not in react-query. The downgrade works by accident.

The stream-reading loop in router-ssr-query-core hydrates before it checks done (packages/router-ssr-query-core/src/index.ts, L194-L207):

reader.read().then(async function handle({ done, value }) {
queryHydrate(queryClient, value, hydrateOptions) // ← value is undefined here
if (done) return // ← too late
const result = await reader.read()
return handle(result)
}).catch((err) => console.error('Error reading query stream:', err))
The final reader.read() of any ReadableStream always resolves { done: true, value: undefined }, so queryHydrate is always called once with undefined.

Why it only shows up now. query-core's hydrate() used to take dehydratedState: unknown and early-return on non-objects, which silently absorbed that call. That guard was removed:

• export function hydrate(client, dehydratedState: unknown, options?): void {
• if (typeof dehydratedState !== 'object' || dehydratedState === null) return

• export function hydrate(client, dehydratedState: Partial, options?): void {
• const mutationCache = client.getMutationCache()
  ...
  dehydratedState.mutations?.forEach(...)
  I bisected the published tarballs — the guard disappears in @tanstack/query-core@5.102.1:

version guard
5.101.4 ✅
5.102.0 ✅
5.102.1 ❌
5.102.2 ❌
So the latent ordering bug has always been there; 5.102.1 just stopped hiding it. Downgrading react-query re-hides it rather than fixing it.

Severity: cosmetic. Every real chunk is hydrated — only the terminal read throws, and it carries no data. But it's a red console error on every page load of every TanStack Start app.

Fix — move the done check above the hydrate call:

.then(async function handle({ done, value }) {

• queryHydrate(queryClient, value, hydrateOptions)
• if (done) return

• if (done) return
• queryHydrate(queryClient, value, hydrateOptions)
  const result = await reader.read()
  return handle(result)
  })
  Happy to open a PR if that's useful.

Workaround without downgrading, for anyone who needs to stay on the current react-query: wrap the queryStream you hand to the integration so the terminal read yields an empty state instead of undefined. Hydrating { mutations: [], queries: [] } is a no-op, so the if (done) return then exits cleanly — and it self-neutralises once this is fixed upstream.

Thanks for the deep dive — that's a really clear root-cause writeup. Would love it if you opened a PR for the fix, that'd be very useful. Appreciate you tracking this down!