TanStack Query Hydration 오류 해결: QueryClient 설정 기준

React HTML hydration과 Query 캐시 hydration은 다른 문제

React hydration은 서버 HTML에 브라우저의 React 트리를 연결하는 과정이고, Query hydration은 별도 QueryClient에 서버 데이터 스냅샷을 복원하는 과정입니다. 두 환경이 같은 메모리 인스턴스를 공유하는 것이 아닙니다. 잘못된 중첩 태그, 렌더 중 Date.now·난수·locale 차이, 서버에서 없는 window 값도 HTML 불일치를 만들 수 있습니다. 캐시 키가 틀린 경우에는 데이터 재요청만 나타나고 React hydration 경고는 없을 수도 있습니다.

요청마다 만드는 서버 QueryClient를 모듈 전역 singleton으로 바꾸면 사용자별 캐시가 요청 사이에 섞일 수 있습니다. 브라우저 client는 앱 생명주기 동안 재사용하되 로그인 사용자 전환 시 민감한 캐시를 정리하는 정책이 필요합니다. Client Component라는 이름도 브라우저에서만 실행된다는 뜻은 아닙니다. 최초 서버 렌더에도 참여할 수 있습니다.

staleTime은 hydration 완료 시각부터 새로 세지 않습니다. 서버의 dataUpdatedAt을 유지하므로 prefetch 후 오래 지났다면 브라우저에서 곧바로 refetch하는 것이 정상입니다. 짧은 staleTime을 무조건 늘리기 전에 HTML/CDN 캐시의 나이, 서버 시계, 현재 key와 옵션을 확인합니다. 이미 더 최신인 브라우저 캐시가 있으면 오래된 dehydrated 데이터로 덮어쓰지 않는지도 진단합니다.

기본 dehydrate는 성공한 query를 포함합니다. prefetchQuery는 오류를 호출자에게 throw하지 않으므로 try/catch만 붙여 “서버 조회 성공”을 판단하지 않습니다. 페이지 자체의 실패 정책이 필요하면 fetchQuery를 await하고 오류를 처리하거나 getQueryState로 실패 상태를 검사합니다. pending query 전달은 별도의 streaming 구성과 shouldDehydrateQuery 정책이 필요한 심화 범위입니다. staleTime을 조정한다고 pending Promise의 rejection이 해결되지는 않습니다.

dehydrate 결과는 곧 JSON 문자열이라는 뜻이 아닙니다. Date·Error·undefined 등 변환이 필요한 값은 프레임워크 직렬화 정책을 따라야 합니다. 인증 토큰이나 서버 전용 비밀 값을 캐시에 넣어 클라이언트로 보내지 않습니다. 사용자 데이터가 든 JSON을 HTML script에 수동 삽입하지 말고 프레임워크의 안전한 직렬화 경로를 사용하세요. 이 예제는 문자열·배열·객체만 가진 fixture를 JSON 왕복으로 검사합니다.

내 증상이 이거면 여기부터 보세요

Next.js에서 TanStack Query를 붙이면 서버에서 데이터를 미리 가져오고 클라이언트에서 이어받는 구조가 됩니다. 이때 QueryClient를 매 렌더마다 새로 만들거나 queryKey가 조금만 달라져도 서버 캐시가 클라이언트에서 이어지지 않습니다.

Hydration 오류는 콘솔 문구만 복사하기보다 서버와 클라이언트의 queryKey, dehydrate 결과 전달 여부, QueryClientProvider 위치를 함께 기록해야 합니다. 이 정보가 있어야 React HTML 불일치와 TanStack Query 캐시 연결 실패를 구분할 수 있습니다.

Hydration failed because the initial UI does not match what was rendered on the server.
No QueryClient set, use QueryClientProvider to set one
A query that was dehydrated as pending ended up rejecting
Text content does not match server-rendered HTML

먼저 적용할 핵심 수정 코드

다음 Next.js App Router 코드는 적용 구조를 설명하는 참고용입니다. 아래 ZIP은 Next.js 앱이 아니라 캐시 전달 실험이며 실제 Next.js 서버 실행을 검증하지 않았습니다. PostList는 같은 [“posts”] key의 useQuery를 사용하는 클라이언트 컴포넌트여야 하며, Provider는 app/layout의 children을 감쌉니다.

원인 설명을 오래 읽기 전에 아래 설정부터 현재 코드와 대조해보세요. Provider에서 QueryClient를 안정적으로 만들고, 서버 컴포넌트에서 prefetchQuery 후 dehydrate 결과를 HydrationBoundary에 넘깁니다. 중요한 것은 오류를 덮는 옵션을 추가하는 것이 아니라, 실행 환경과 설정 파일이 같은 기준으로 동작하게 만드는 것입니다.

클라이언트 Provider 설정

"use client"

import { QueryClient, QueryClientProvider, isServer } from "@tanstack/react-query"

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000,
      },
    },
  })
}

let browserQueryClient: QueryClient | undefined

function getQueryClient() {
  if (isServer) return makeQueryClient()
  if (!browserQueryClient) browserQueryClient = makeQueryClient()
  return browserQueryClient
}

export function QueryProvider({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient()

  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  )
}

클라이언트에서 QueryClient가 렌더마다 새로 만들어지지 않도록 브라우저용 QueryClient를 재사용합니다. TanStack Query의 Next.js App Router 예시는 서버에서는 요청마다 새 QueryClient를 만들고, 브라우저에서는 이미 만든 QueryClient를 재사용하는 패턴을 제시합니다.

서버 prefetch와 HydrationBoundary

import { HydrationBoundary, QueryClient, dehydrate } from "@tanstack/react-query"

async function getPosts() {
  return [{ id: 1, title: "서버 fixture 문서" }]
}

export default async function Page() {
  const queryClient = new QueryClient()

  await queryClient.prefetchQuery({
    queryKey: ["posts"],
    queryFn: getPosts,
  })

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

서버에서 prefetch한 queryKey와 클라이언트 useQuery의 queryKey가 같아야 캐시가 이어집니다.

왜 이런 오류가 생기는가

Hydration은 서버에서 만든 HTML과 클라이언트가 처음 그린 화면을 맞추는 과정입니다. TanStack Query 데이터가 서버와 클라이언트에서 다르게 들어오면 React는 같은 화면이라고 판단하지 못합니다.

QueryClient는 캐시 저장소입니다. 클라이언트 컴포넌트가 렌더될 때마다 QueryClient를 새로 만들면 방금 받은 캐시를 스스로 버리는 구조가 됩니다.

HydrationBoundary는 서버에서 dehydrate한 캐시를 클라이언트 영역으로 넘기는 경계입니다. 공식 문서 기준으로 HydrationBoundary는 useQueryClient가 반환하는 QueryClient에 이전에 dehydrated 된 state를 병합합니다. Provider만 있다고 자동으로 서버 prefetch 결과가 연결되는 것은 아닙니다.

실제 작업에서 점검하는 순서

먼저 오류를 No QueryClient set, Hydration failed, 불필요한 재요청 중 하나로 나눕니다. Provider 누락은 클라이언트 트리, hydration 실패는 HTML 일치와 서버 상태 전달, 재요청은 queryKey와 staleTime 순서로 확인합니다.

두 번째로 한 번에 여러 설정을 바꾸지 않습니다. TanStack Query Hydration 오류를 해결하다 보면 관련 파일을 전부 고치고 싶어지지만, 그러면 어떤 변경이 실제 해결책이었는지 알기 어렵습니다. 핵심 설정 하나를 바꾸고 검증 명령을 실행한 뒤 다음 설정으로 넘어가야 합니다.

저장소에는 QueryClient 생성 함수, 앱 루트 Provider, 서버의 prefetchQuery와 HydrationBoundary를 한 흐름으로 남깁니다. 서버와 브라우저가 같은 queryKey 팩토리를 사용하면 팀원이 기능을 추가해도 캐시 키가 어긋날 가능성이 줄어듭니다.

그래도 안 될 때 볼 예외 케이스

수정 뒤에도 hydration 경고가 남으면 브라우저 캐시보다 QueryClient 생성 시점부터 확인합니다. 클라이언트 렌더마다 새 인스턴스가 생기지 않는지, pending query를 전달하도록 별도 설정했는지와 그 Promise가 왜 거부됐는지, React 개발 모드의 이중 실행에서 값이 달라지지 않는지 차례로 봅니다.

• Next.js App Router에서 Provider는 클라이언트 컴포넌트여야 합니다.
• SSR에서는 staleTime을 0보다 크게 잡아 hydration 직후 클라이언트에서 즉시 refetch되는 상황을 줄이는 것이 일반적입니다.
• queryFn 안에서 window나 localStorage를 바로 읽으면 서버 prefetch 단계에서 실패합니다.

다음에 같은 문제를 줄이는 체크리스트

TanStack Query Hydration 문제는 Provider, QueryClient, HydrationBoundary, queryKey가 한 세트로 맞아야 줄어듭니다. 한 군데만 고치면 해결된 것처럼 보이다가 다른 페이지에서 같은 문제가 반복될 수 있습니다.

• QueryClientProvider가 앱 루트에 있는지 확인합니다.
• 클라이언트 QueryClient를 렌더마다 새로 만들지 않습니다.
• prefetchQuery와 useQuery의 queryKey를 같은 배열로 맞춥니다.
• dehydrate 결과를 HydrationBoundary state로 넘깁니다.

결국 TanStack Query Hydration 오류는 한 줄짜리 우회 코드보다 확인 순서가 중요합니다. 에러 문구를 단계별로 나누고, 설정 파일과 실행 명령을 같은 기준으로 맞추면 같은 문제를 훨씬 짧게 끝낼 수 있습니다. 공식 기준은 Advanced Server Rendering, Server Rendering & Hydration, Hydration API, QueryClientProvider 문서에서 확인했습니다.