트러블슈팅
Next.js 16에서 hydration mismatch가 나는 진짜 이유

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.js | 16.3.1 |
| React | 19.2.8 |
| Node | 24.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 중첩도 원인이 된다. 브라우저가 마크업을 교정하면서 트리가 서버와 달라진다.- 프로덕션 빌드에서만 재현되는 경우는 확인하지 못했다.