Hydration failed because the server rendered HTML didn't match the client.
빠른 답변
- 이 오류는 무엇인가요?
- 서버가 만든 HTML과 브라우저의 첫 React 렌더링 결과가 달라 hydration mismatch가 발생했는지 확인합니다.
- 이 문서에서 확인할 수 있는 범위는 어디까지인가요?
- React hydration mismatch는 서버가 만든 HTML과 브라우저의 첫 렌더링 결과가 다를 때 발생합니다. 시간·난수·브라우저 전용 API·확장 프로그램처럼 서버와 클라이언트의 입력이 달라지는 조건을 먼저 분리합니다.
- 무엇을 먼저 확인해야 하나요?
- 로그 또는 화면에 `Hydration failed because the server rendered HTML didn't match the client.`가 표시되는지 확인합니다.
이 문서의 범위
이 문서는 화면·로그의 오류 원문 또는 상태를 공식 자료와 대조하는 데 사용합니다. 이 문구만으로 실제 원인이나 변경 방법을 확정하지 않으며, 아래 관련 기술 문서에서 적용 환경을 추가로 확인해야 합니다.
현재 증상
- 애플리케이션 오류 메시지
먼저 확인할 항목
로그 또는 화면에 `Hydration failed because the server rendered HTML didn't match the client.`가 표시되는지 확인합니다.
서버 응답 HTML과 브라우저 첫 렌더링에서 시간·난수·지역 설정 값이 달라지는지 확인합니다.
렌더링 중 `window`, `document` 등 브라우저 전용 API를 읽는지 확인합니다.
브라우저 확장 프로그램을 끈 상태에서도 같은 오류가 재현되는지 확인합니다.
피해야 할 조치
주의
- 경고를 숨기는 옵션을 먼저 적용하지 말고 서버·클라이언트 출력 차이를 기록합니다.
- 사용자별 데이터나 인증 상태를 서버·클라이언트에서 다르게 읽는 코드를 무작정 지우지 않습니다.
오류 원문·상태 확인 범위
확인 방법
- 오류 원문과 발생한 URL, 서버 렌더링 여부를 기록합니다.
- 서버와 브라우저 첫 렌더링에서 시간·난수·지역 설정·사용자별 값이 다른지 비교합니다.
- 렌더링 중 브라우저 전용 API를 호출하는지 확인합니다.
- 확장 프로그램을 끈 새 브라우저에서도 같은 결과인지 확인합니다.
서버와 브라우저가 같은 입력으로 첫 화면을 만들지 못하면 hydration이 완료되지 않을 수 있습니다. 원인을 확인하기 전에 경고를 숨기거나 서버와 클라이언트 중 한쪽의 화면을 임의로 고정하지 마십시오.
참고 자료
Minified React error (새 창에서 열림)
React · 공식 자료 · 확인 범위: hydration-mismatch, server-client-render-difference, development-error-details · 확인일: 2026-07-27