React 화면이 처음 로드될 때 hydration 오류가 나요
React 서버 렌더링 화면의 첫 HTML과 브라우저 렌더링이 다를 때 발생한 문구와 재현 조건을 기록합니다.
빠른 답변
React hydration 오류는 서버가 만든 HTML과 브라우저의 첫 React 렌더링 결과가 다를 때 발생합니다. 시간·난수·브라우저 전용 API·사용자별 데이터처럼 입력이 달라지는 조건을 먼저 분리합니다.
이 가이드가 맞는 경우
- 애플리케이션 오류 메시지
상황별 다음 단계
호스팅사·개발자에게 전달할 내용
변경 전 기록
- 오류가 난 URL, 서버 렌더링 사용 여부, 오류 발생 시각을 전달합니다.
- 서버 응답 HTML과 브라우저 첫 화면에서 달라진 영역을 기록합니다.
- 인증 토큰, 쿠키, 개인정보는 전달하지 않습니다.
알아둘 점
이 문서는 React 화면이 처음 로드될 때 hydration 오류가 나요라는 시작 상황에서 서버와 브라우저의 첫 렌더링 차이를 확인하는 순서를 제공합니다.
먼저 확인할 것
- 오류 원문과 발생한 URL을 기록합니다.
- 렌더링 중
Date,Math.random(), 지역 설정, 사용자별 값을 직접 읽는지 확인합니다. window,document같은 브라우저 전용 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. 문서를 확인합니다. 일치하지 않으면 원문을 보존한 뒤 다른 React 오류 문서를 선택하세요.
참고 자료
Minified React error (새 창에서 열림)
React · 공식 자료 · 확인 범위: hydration-mismatch, server-client-render-difference · 확인일: 2026-07-27