지니로그

트러블슈팅

Next.js 16에서 hydration mismatch가 나는 진짜 이유

English로 보기

브라우저 콘솔의 hydration diff — 서버가 낸 '2026년 8월 17일'이 빨강으로, 클라이언트가 낸 '2026년 8월 16일'이 청록으로 표시된 화면

hydration mismatch의 대부분은 Date, Math.random, 로케일 포맷, 브라우저 전용 API 중 하나에서 나온다. React 19는 실패한 DOM 노드를 에러에 직접 찍어주므로, 먼저 콘솔의 diff를 읽어 원인을 특정한 뒤 useEffect 지연 또는 suppressHydrationWarning으로 좁혀 해결한다.

증상

빌드는 성공하는데 브라우저 콘솔에 아래 에러가 뜨고, 화면이 잠깐 깜빡인 뒤 다시 그려진다.

Error: Hydration failed because the server rendered HTML didn't match the client.
As a result this tree will be regenerated on the client.

서버가 만든 HTML과 클라이언트의 첫 렌더 결과가 다르면 React가 해당 트리를 통째로 버리고 다시 그린다. 깜빡임은 그 재생성이 눈에 보이는 것이다.

재현 환경

항목버전
Next.js16.3.1
React19.2.8
Node24.11.0
확인일2026-08-17

왜 이 에러가 나는가

서버와 클라이언트가 서로 다른 입력으로 렌더링했기 때문이다. 원인은 대부분 아래 넷 중 하나다.

원인왜 갈리는가
new Date() / Date.now()서버 렌더 시각과 클라이언트 렌더 시각이 다르다
Math.random()값이 매번 다르다
로케일·타임존 포맷서버는 UTC, 브라우저는 사용자 타임존을 쓴다
window / localStorage서버에는 없어서 분기 결과가 갈린다

가장 흔한 것은 세 번째다. toLocaleDateString() 은 실행 환경의 타임존을 따르므로, 서버(UTC)와 한국 사용자의 브라우저(KST)에서 날짜가 하루 어긋날 수 있다.

원인을 어떻게 특정하는가

React 19는 에러 메시지에 실패한 DOM 노드를 직접 찍어준다. 콘솔에서 -(서버)와 +(클라이언트) 로 표시된 diff를 먼저 읽는다.

  <time datetime="2026-08-17">
-   2026년 8월 17일
+   2026년 8월 16일

날짜가 하루 차이 난다면 타임존 문제로 좁혀진다. 추측으로 코드를 고치기 전에 diff부터 읽는 편이 빠르다.

해결

클라이언트에서만 계산해야 하는 값이면 렌더를 미룬다

"use client";

import { useEffect, useState } from "react";

export function LocalDate({ iso }: { iso: string }) {
  const [formatted, setFormatted] = useState<string | null>(null);

  useEffect(() => {
    setFormatted(new Date(iso).toLocaleDateString());
  }, [iso]);

  // 첫 렌더는 서버와 동일하게 ISO 문자열을 낸다.
  return <time dateTime={iso}>{formatted ?? iso}</time>;
}

서버와 클라이언트의 첫 렌더가 같아지고, 지역화된 표기는 마운트 이후에 나타난다.

값이 다른 것이 정상이면 경고를 끈다

<time dateTime={iso} suppressHydrationWarning>
  {new Date(iso).toLocaleDateString()}
</time>

suppressHydrationWarning 은 해당 요소의 텍스트 한 겹에만 적용된다. 자식 트리 전체를 무시하지 않으므로 남용해도 다른 버그를 가려주지는 않는다.

포맷을 고정한다

가장 견고한 방법은 애초에 환경 의존을 없애는 것이다. 타임존을 명시하면 서버든 클라이언트든 결과가 같다.

new Intl.DateTimeFormat("ko-KR", { timeZone: "Asia/Seoul" }).format(new Date(iso));

왜 이 해결이 맞는가

suppressHydrationWarning 만 붙이는 것은 증상을 덮는 쪽에 가깝다. 경고는 사라지지만 서버가 보낸 HTML은 여전히 틀린 값이고, JS가 실행되기 전까지 사용자는 그 틀린 값을 본다. 검색엔진이 수집하는 것도 그 값이다.

반면 타임존을 명시하는 방식은 서버 HTML 자체가 처음부터 옳다. 그래서 표시용 날짜에는 세 번째 방법을, 진짜로 클라이언트에서만 알 수 있는 값(예: localStorage 에 저장된 사용자 설정)에는 첫 번째 방법을 쓴다.

이것도 확인해볼 것

  • 브라우저 확장이 DOM을 건드려도 같은 에러가 난다. 시크릿 모드에서 재현되는지 먼저 확인한다.
  • <p> 안에 <div> 를 넣는 등 유효하지 않은 HTML 중첩도 원인이 된다. 브라우저가 마크업을 교정하면서 트리가 서버와 달라진다.
  • 프로덕션 빌드에서만 재현되는 경우는 확인하지 못했다.