Fix/infinite query hydration 8825 #10074

chosule · 2026-01-27T16:15:08Z

Note: This solution was discussed and approved by @TkDodo in Discussion #10027

Problem

When prefetchInfiniteQuery fails on the server, useSuspenseInfiniteQuery on the client doesn't return the correct infinite query structure ({ pages: [], pageParams: [] }), causing a runtime error when accessing data.pages:

TypeError: Cannot read properties of undefined (reading 'length')

Root Cause

Infinite query behavior information gets lost during hydration:

infiniteQueryBehavior is attached when prefetchInfiniteQuery runs on the server
This behavior info isn't preserved during dehydration
On the client, it gets restored as a regular query during hydration
Error occurs when data is accessed before InfiniteQueryObserver attaches the behavior

Solution

Set up infinite query behavior at hydration time to guarantee correct data structure for both success and failure cases.

Changes

1. Added `queryType` field to `DehydratedQuery`

Metadata to identify infinite queries
Stores 'query' | 'infiniteQuery' value

2. Auto-detect query type during dehydration

Checks for initialPageParam presence to identify infinite queries
Stores result in queryType field

3. Auto-configure behavior during hydration

Attaches infiniteQueryBehavior when queryType is 'infiniteQuery'

4. Handle failed promises

Rejected promises aren't passed as initialPromise
Allows automatic retry on the client

Modified Files

packages/query-core/src/hydration.ts
packages/query-core/src/__tests__/hydration.test.tsx

Tests

All 35 tests passing (including 2 new tests)

New tests added:

should preserve queryType for infinite queries during hydration
should attach infiniteQueryBehavior during hydration

Checklist

Added queryType: 'query' | 'infiniteQuery' field to DehydratedQuery
Auto-detect infinite queries during dehydration by checking initialPageParam
Auto-configure infiniteQueryBehavior for infinite queries during hydration
Added test cases for hydrated infinite query behavior
Guarantee correct data structure for both success and failure cases

Summary by CodeRabbit

Bug Fixes
- Preserve infinite query behavior and pagination state during SSR hydration so hydrated clients retain pages and cursors.
Tests
- Added hydration tests to validate infinite query preservation and post-hydration fetching behavior.
Chores
- Added release metadata documenting this patch release.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

…8825)

changeset-bot · 2026-01-27T16:15:13Z

🦋 Changeset detected

Latest commit: 161c143

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages

Name	Type
@tanstack/query-core	Patch
@tanstack/angular-query-experimental	Patch
@tanstack/query-async-storage-persister	Patch
@tanstack/query-broadcast-client-experimental	Patch
@tanstack/query-persist-client-core	Patch
@tanstack/query-sync-storage-persister	Patch
@tanstack/react-query	Patch
@tanstack/solid-query	Patch
@tanstack/svelte-query	Patch
@tanstack/vue-query	Patch
@tanstack/angular-query-persist-client	Patch
@tanstack/react-query-persist-client	Patch
@tanstack/solid-query-persist-client	Patch
@tanstack/svelte-query-persist-client	Patch
@tanstack/react-query-devtools	Patch
@tanstack/react-query-next-experimental	Patch
@tanstack/solid-query-devtools	Patch
@tanstack/svelte-query-devtools	Patch
@tanstack/vue-query-devtools	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-01-27T16:15:53Z

📝 Walkthrough

Walkthrough

Adds explicit support for infinite queries during de/rehydration: dehydration records queryType, hydration restores it and applies infiniteQueryBehavior for infinite queries, and promise handling during hydration is hardened to avoid unhandled rejections. New tests and a changeset were added.

Changes

Cohort / File(s)	Summary
Metadata `\.changeset/stupid-seals-live.md`	New changeset documenting a patch release for `@tanstack/query-core` noting preservation of infinite query behavior during SSR hydration.
Core Hydration Logic `packages/query-core/src/hydration.ts`	Added `queryType?: 'query'
Hydration Tests `packages/query-core/src/__tests__/hydration.test.tsx`	Added two tests validating preservation of infinite query type and attachment of `infiniteQueryBehavior` across dehydrate→hydrate and subsequent `fetchInfiniteQuery` behavior.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Server as Server (prefetch)
participant Dehydrator as Dehydrator
participant Serialized as Serialized State
participant Client as Client (hydrate)
participant QueryClient as QueryClient
Server->>Dehydrator: prefetchInfiniteQuery -> capture Query (pages/pageParams)
Dehydrator->>Serialized: dehydrate(query + queryType:'infiniteQuery')
Serialized-->>Client: send dehydrated state
Client->>QueryClient: hydrate(state)
QueryClient->>QueryClient: restore query with infiniteQueryBehavior based on queryType
Client->>QueryClient: fetchInfiniteQuery() -> uses restored behavior and pages/pageParams

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Fix unhandled promise rejections during de/rehydration of pending queries #9752 — Similar changes addressing promise handling for dehydrated thenables to prevent unhandled rejections.
Fix/streamed query consume aware signal #9963 — Changes to infiniteQueryBehavior which this PR imports and applies during hydration.

Suggested reviewers

TkDodo

Poem

"🐰 I hopped through state both wide and deep,
Saved pages and cursors for you to keep,
Dehydrate, hydrate — no data astray,
Infinite hops now find their way,
Cheers to queries that safely leap!"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Fix/infinite query hydration 8825' directly references the issue being fixed and clearly indicates the primary change involves fixing infinite query hydration.
Description check	✅ Passed	The description comprehensively covers the problem, root cause, solution, changes, modified files, tests, and includes a completed checklist matching the required template.
Linked Issues check	✅ Passed	The PR fully addresses issue `#8825` by implementing automatic infinite query behavior attachment during hydration, preserving correct data structure, handling failed promises, and adding comprehensive tests.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing infinite query hydration and are within the scope of issue `#8825`; no unrelated modifications were introduced.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

nx-cloud · 2026-01-29T13:59:16Z

View your CI Pipeline Execution ↗ for commit 161c143

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	⛔ Cancelled	18s	View ↗

☁️ Nx Cloud last updated this comment at 2026-01-29 14:02:42 UTC

TkDodo · 2026-01-29T14:05:16Z

packages/query-core/src/hydration.ts

+        const queryOptions: any = {
+          ...client.getDefaultOptions().hydrate?.queries,
+          ...options?.defaultOptions?.queries,
+          queryKey,
+          queryHash,
+          meta,
+        }


can we keep this inlined please and just conditionally assign behavior:

behavior: queryType === 'infiniteQuery' ? (infiniteQueryBehavior() as QueryBehavior<unknown, unknown, unknown>) : undefined,

TkDodo · 2026-01-29T18:12:54Z

packages/query-core/src/hydration.ts

+        const isRejectedThenable =
+          promise &&
+          typeof promise === 'object' &&
+          'status' in promise &&
+          (promise as any).status === 'rejected'
+
+        if (!isRejectedThenable) {
+          query
+            .fetch(undefined, {
+              // RSC transformed promises are not thenable
+              initialPromise: Promise.resolve(promise).then((resolvedData) => {
+                return deserializeData(resolvedData)
+              }),
+            })
+            // Avoid unhandled promise rejections
+            .catch(noop)


I don’t understand what this change has to do with infinite queries ?

chosule added 2 commits January 28, 2026 00:46

fix: preserve infinite query behavior during SSR hydration (TanStack#…

997314a

…8825)

chore: add changeset for TanStack#8825

fe181a8

github-actions bot added the package: query-core label Jan 27, 2026

ci: apply automated fixes

161c143

TkDodo reviewed Jan 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix/infinite query hydration 8825 #10074

Fix/infinite query hydration 8825 #10074

chosule commented Jan 27, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 27, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 27, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

nx-cloud bot commented Jan 29, 2026 •

edited

Loading

Uh oh!

TkDodo Jan 29, 2026

Uh oh!

TkDodo Jan 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Fix/infinite query hydration 8825 #10074

Are you sure you want to change the base?

Fix/infinite query hydration 8825 #10074

Conversation

chosule commented Jan 27, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Root Cause

Solution

Changes

1. Added queryType field to DehydratedQuery

2. Auto-detect query type during dehydration

3. Auto-configure behavior during hydration

4. Handle failed promises

Modified Files

Tests

Checklist

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

nx-cloud bot commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TkDodo Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

TkDodo Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

chosule commented Jan 27, 2026 •

edited by coderabbitai bot

Loading

1. Added `queryType` field to `DehydratedQuery`

changeset-bot bot commented Jan 27, 2026 •

edited

Loading

coderabbitai bot commented Jan 27, 2026 •

edited

Loading

nx-cloud bot commented Jan 29, 2026 •

edited

Loading