QueryKey mismatch causes server 500 with Next.js App Router (Server Components + openapi-react-query)

[darkmyu]

When using openapi-react-query with Next.js 15 App Router and Server Components, a mismatch occurs between automatically generated queryKeys:

• Server-side: requires manually passing cookies/headers

• Client-side: auto-generated queryKey does not include these headers

• Result: dehydrated data is rendered correctly 🎯 but Next.js logs a 500 Internal Server Error on the server ❌

Because the two environments generate different query keys, React Query treats them as different queries.

import createFetchClient from 'openapi-fetch';
import createClient from 'openapi-react-query';
import type { paths } from './schema';

export const api = createFetchClient<paths>({
  baseUrl: process.env.NEXT_PUBLIC_API_URL,
  credentials: 'include',
});

export const $api = createClient(api);

async function ServerComponent() {
  const queryClient = getQueryClient();
  const cookieStore = await cookies();
  
  queryClient.fetchQuery(
    $api.queryOptions('get', '/api', {
      headers: {
        Cookie: cookieStore.toString(),
      },
    }),
  );
  
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <ClientComponent />
    </HydrationBoundary>
  );
}

'use client'

function ClientComponent() {
  const { data } = $api.useSuspenseQuery('get', '/api')

  // ...
}

["get","/api"] // ClientComponent queryKey

["get","/api",{"headers":{"Cookie":"..."}] // ServerComponent queryKey

Any guidance or recommended fix for this issue would be appreciated.

[darkmyu]

Although manually specifying the queryKey and queryFn resolves the issue, I would prefer to continue relying on the auto-generated behavior rather than overriding it.