SSR prefetchInfiniteQuery causes TypeError on client

[Hina0222]

Hello, I’m learning TanStack Query.
I ran into an issue when testing Server Components(Next.js 16, app router) with missing access tokens:

Situation:

• I am using prefetchInfiniteQuery in a Server Component to prefetch data.
• If the API call fails due to missing authentication (no token), the query fails.
• On the client, I continue fetching using useSuspenseInfiniteQuery.
• However, the following error occurs on the client:

TypeError: Cannot read properties of undefined (reading 'length')
at getNextPageParam (infiniteQueryBehavior.ts:136:27)
at hasNextPage (infiniteQueryBehavior.ts:164:10)

• It seems there is an issue with how infiniteQuery handles errors thrown in Server Components.
• After this error, the client successfully fetches again once the token is refreshed, but the UI still shows an error due to the initial failure.
• prefetchQuery or cases where the access token exists work correctly.

---

Question:
How should I handle prefetchInfiniteQuery in Server Components so that the client can safely continue infinite queries even if the server throws an error?

---

Relevant Code:

page.tsx

<ServerFetchBoundary infiniteQueryOptions={getFeedsInfiniteQueryOptions()}>
  <FeedList />
</ServerFetchBoundary>

client component

function FeedList({ sort = 'latest' }: FeedListProps) {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
    useGetFeedsSuspenseInfiniteQuery(sort);
}

queryOptions

export const getFeedsInfiniteQueryOptions = (sort: FeedQuery['sort'] = 'latest') => {
  return {
    queryKey: feedQueryKeys.list({ sort }),
    queryFn: ({ pageParam = 0 }: { pageParam: number }) =>
      getFeeds({ sort, cursor: pageParam || undefined }),
    initialPageParam: 0,
    getNextPageParam: (lastPage: FeedListResponse) =>
      lastPage.hasNext ? lastPage.cursor : undefined,
  };
};

ServerFetchBoundary.tsx

export const ServerFetchBoundary = async ({
  children,
  queryOptions,
  infiniteQueryOptions,
}: ServerFetchBoundaryProps) => {
  await connection();
  const queryClient = getQueryClient();

  const queries = queryOptions ? (Array.isArray(queryOptions) ? queryOptions : [queryOptions]) : [];
  const infiniteQueries = infiniteQueryOptions
    ? Array.isArray(infiniteQueryOptions)
      ? infiniteQueryOptions
      : [infiniteQueryOptions]
    : [];

  queries.forEach(opt => {
    queryClient.prefetchQuery(opt);
  });

  infiniteQueries.forEach(opt => {
    queryClient.prefetchInfiniteQuery(opt);
  });

  return <HydrationBoundary state={dehydrate(queryClient)}>{children}</HydrationBoundary>;
};

queryClientOption

dehydrate: {
  shouldDehydrateQuery: query =>
    defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
  shouldRedactErrors: () => {
    return false;
  },
},

---

Is there a recommended way to handle prefetchInfiniteQuery in Server Components so that the client can safely continue infiniteQuery fetching even when the server throws an error?

Thank you for your help!

[TkDodo]

streaming doesn’t yet work with infinite queries:

• Next.js: exception encountered in prefetchInfiniteQuery causes useSuspenseInfiniteQuery to fail #8825

[sueun-dev]

The root cause here is that your ServerFetchBoundary isn't awaiting the prefetches, which triggers the streaming path that's broken for infinite queries (the bug TkDodo linked).

Here's what happens step by step:

1. infiniteQueries.forEach(opt => queryClient.prefetchInfiniteQuery(opt)) fires the prefetch but doesn't await it, so the query stays in pending state when dehydrate(queryClient) runs
2. Because you have || query.state.status === 'pending' in shouldDehydrateQuery, the pending promise gets dehydrated and sent to the client
3. On the client, hydration calls query.fetch(undefined, { initialPromise }) to pick up the stream — but critically, it does not attach infiniteQueryBehavior because hydration has no way to distinguish infinite queries from regular ones
4. When the server fetch fails (auth error), the client's retry runs the queryFn — but without infiniteQueryBehavior, the response never gets wrapped into { pages, pageParams } format
5. getNextPageParam receives undefined as lastPage and crashes at lastPage.hasNext

The fix: await your prefetches and catch auth failures

Update ServerFetchBoundary to properly await everything:

export const ServerFetchBoundary = async ({
  children,
  queryOptions,
  infiniteQueryOptions,
}: ServerFetchBoundaryProps) => {
  await connection();
  const queryClient = getQueryClient();

  const queries = queryOptions
    ? Array.isArray(queryOptions) ? queryOptions : [queryOptions]
    : [];
  const infiniteQueries = infiniteQueryOptions
    ? Array.isArray(infiniteQueryOptions) ? infiniteQueryOptions : [infiniteQueryOptions]
    : [];

  await Promise.all([
    ...queries.map(opt => queryClient.prefetchQuery(opt).catch(() => {})),
    ...infiniteQueries.map(opt => queryClient.prefetchInfiniteQuery(opt).catch(() => {})),
  ]);

  return <HydrationBoundary state={dehydrate(queryClient)}>{children}</HydrationBoundary>;
};

The .catch(() => {}) is intentional. When the auth error hits:

• The prefetch is awaited and settles as error state
• defaultShouldDehydrateQuery does not include error state queries by default
• So nothing gets dehydrated for that query — the client starts with no cached state and fetches fresh after the token refreshes

This avoids the streaming path entirely for all these queries, which is exactly TkDodo's recommended workaround: "don't stream promises for infinite queries, but await them on the server."

Why not just make getNextPageParam defensive?

getNextPageParam: (lastPage: FeedListResponse | undefined) =>
  lastPage?.hasNext ? lastPage.cursor : undefined,

This silences the crash but doesn't fix the underlying data structure problem — the client is still working with a malformed query state that'll cause other subtle issues.

The upstream fix for the streaming case is being tracked in PR #9633 if you need that path later.

[Hina0222]

Thank you for the detailed explanation!

[Rick1330]

Resolving the TypeError: Cannot read properties of undefined (reading 'length') in SSR

I see you're running into a tricky TypeError when a prefetchInfiniteQuery fails on the server (e.g., due to a 401 Unauthorized) and then hydrates to the client. This happens because TanStack Query's infinite query behavior expects a specific structure for "failed" or "empty" pages during hydration.

The Root Cause:
When the server-side prefetch fails, the dehydrate state contains a query with a status: 'error'. However, if your initialPageParam and getNextPageParam logic doesn't account for an empty or undefined lastPage during the first client-side render (hydration), the internal infiniteQueryBehavior tries to access .pages or .pageParams which might be missing or incorrectly structured, leading to the length error.

The Solution: Robust getNextPageParam and Error Handling

To fix this, you need to ensure that your queryOptions can gracefully handle the "no data" state that occurs after a server-side failure.

1. Update getNextPageParam to be more defensive:

export const getFeedsInfiniteQueryOptions = (sort: FeedQuery['sort'] = 'latest') => {
  return {
    queryKey: feedQueryKeys.list({ sort }),
    queryFn: ({ pageParam = 0 }: { pageParam: number }) =>
      getFeeds({ sort, cursor: pageParam || undefined }),
    initialPageParam: 0,
    getNextPageParam: (lastPage: FeedListResponse | undefined) => {
      // Add a check for undefined lastPage (common after a failed prefetch)
      if (!lastPage || !lastPage.hasNext) return undefined;
      return lastPage.cursor;
    },
  };
};

2. Handle Errors in the Server Boundary:
In your ServerFetchBoundary, consider wrapping the prefetch in a try/catch if you want to prevent a "hard error" from being dehydrated. However, the standard approach is to let the error dehydrate so the client knows it needs to retry.

3. Use useInfiniteQuery (not Suspense) for Auth-heavy routes:
If your query is likely to fail due to missing tokens on the server, useSuspenseInfiniteQuery can be aggressive because it will trigger a suspense fallback immediately. Using the standard useInfiniteQuery and checking isError might give you more control over the "Retry" UI.

Why the error happens specifically in Infinite Queries:

Standard useQuery just sees data: undefined. But useInfiniteQuery must manage an array of pages. If the hydration state says "I have an error" but the internal logic tries to calculate the hasNextPage status based on the (non-existent) pages array, it crashes.

If this fixes the hydration crash for you, please mark it as the answer!