Fix/infinite query hydration 8825

[chosule]

Fixes #8825

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:

1. infiniteQueryBehavior is attached when prefetchInfiniteQuery runs on the server
2. This behavior info isn't preserved during dehydration
3. On the client, it gets restored as a regular query during hydration
4. 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

1. packages/query-core/src/hydration.ts
2. 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

Release Notes

• Bug Fixes
  • Fixed infinite query behavior to be properly preserved and hydrated during server-side rendering, ensuring data structure and pagination state remain intact throughout the hydration process.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: fe181a8

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]

📝 Walkthrough

Walkthrough

The PR adds support for infinite queries during SSR hydration by introducing a queryType field to the DehydratedQuery interface, recording infinite query types during dehydration, applying infiniteQueryBehavior during hydration, and improving promise rejection handling to prevent unhandled errors.

Changes

Cohort / File(s)	Change Summary
Metadata .changeset/stupid-seals-live.md	New changeset documenting patch release for @tanstack/query-core with infinite query behavior preservation during SSR hydration.
Core Hydration Logic packages/query-core/src/hydration.ts	Added queryType field to DehydratedQuery interface; introduced isInfiniteQuery() helper; dehydration now records queryType for infinite queries; hydration extended to propagate queryType and apply infiniteQueryBehavior conditionally; improved promise handling with guard for rejected thenables to prevent unhandled rejections.
Hydration Tests packages/query-core/src/__tests__/hydration.test.tsx	Added two new test cases: one validating queryType preservation for infinite queries across dehydrate/hydrate cycle, another validating infiniteQueryBehavior attachment and fetchInfiniteQuery functionality post-hydration.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Fix unhandled promise rejections during de/rehydration of pending queries #9752 — Addresses promise handling during de/rehydration to prevent unhandled rejections, using similar guard patterns for thenables.
• fix(core): only attach .then and .catch onto a promise if it gets dehydrated #9847 — Modifies hydration promise handling to suppress/unwrap thenables and avoid improper handler attachment.
• Fix/streamed query consume aware signal #9963 — Modifies infiniteQueryBehavior module that this PR directly imports and integrates into the hydration flow.

Suggested reviewers

• TkDodo
• Ephem
• Svish

Poem

🐰 With queryType guarding each infinite quest,
Server and client now pass every test,
Promises handled with careful precision,
Infinite queries flow with precision,
Hydration behaves as the designer's divine vision! 🌿✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

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.
Title check	❓ Inconclusive	The title 'Fix/infinite query hydration 8825' refers to the issue number but lacks clarity about the specific problem being fixed.	Consider a more descriptive title like 'Fix infinite query data structure during hydration in SSR' to better convey the primary change without requiring issue context.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The PR description comprehensively covers the problem, root cause, solution, changes, and includes test results and a detailed checklist.
Linked Issues check	✅ Passed	The PR implementation directly addresses all coding objectives from issue #8825: preserving infinite query structure during hydration, handling failed promises, and ensuring correct data shape for client retries.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing infinite query hydration: the queryType field addition, dehydration detection logic, hydration behavior configuration, and corresponding test coverage are all in scope.

_{✏️ 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

• X
• Mastodon
• Reddit
• LinkedIn

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