AI가 만든 코드에서 window·document를 읽으면 서버에서 실패해요
AI가 만든 React·Next.js 코드가 브라우저에서는 동작하지만 서버 렌더링 또는 정적 생성에서 실패할 때 확인하는 순서입니다.
빠른 답변
서버 렌더링 경로에서 window·document 또는 시간·난수처럼 브라우저마다 달라지는 값을 읽는지 먼저 확인합니다. 서버와 첫 브라우저 렌더링의 입력이 다르면 hydration 오류가 발생할 수 있습니다.
- 적용 범위
- 이 가이드의 시작 증상과 각 분기 조건이 일치하는 경우문맥: 바이브 코딩
- 출처 확인일
- 2026-08-04
- 최종 검토
- 2026-08-04
- 수정일
- 2026-08-04
- 정정 이력
- 2026-07-29 이후 기록 없음
- 대상
- 사이트 운영자, 웹 에이전시, 프리랜서
이 가이드가 맞는 경우
- 애플리케이션 오류 메시지
- 빌드 실패
상황별 다음 단계
호스팅사·개발자에게 전달할 내용
변경 전 기록
- 오류가 난 경로, 서버 로그, 브라우저 콘솔의 원문과 발생 시각을 기록합니다.
- window, document, Date, Math.random, 지역화 포맷을 렌더링 중 호출하는 위치를 표시합니다.
- 토큰·쿠키·개인정보는 전달하지 않습니다.
알아둘 점
먼저 확인할 것
- 오류가 브라우저 첫 화면, 서버 렌더링, 정적 빌드 중 어느 단계에서 발생했는지 나눕니다.
- 컴포넌트의 렌더 함수와 모듈 최상위에서
window,document,localStorage,Date,Math.random()을 읽는지 찾습니다. - 서버 응답 HTML과 브라우저 첫 렌더링의 시간·지역·로그인 상태가 다른지 비교합니다.
- 조건이 일치하면 Hydration failed because the server rendered HTML didn't match the client. 또는 Next.js encountered the unstable value Math.random() while prerendering을 확인합니다.
렌더링에 필요한 값과 브라우저에서만 필요한 동작을 분리하지 않은 상태에서 suppressHydrationWarning을 먼저 추가하지 마십시오. 수정 전 재현 경로와 빌드 명령을 기록해야 합니다.
참고 자료
hydrateRoot | React (새 창에서 열림)
React · 공식 자료 · 확인 범위: 서버에서 생성한 HTML과 브라우저의 첫 렌더링 결과가 일치해야 hydration이 완료됩니다. · 확인일: 2026-08-04
Next.js error documentation (새 창에서 열림)
Next.js · 공식 자료 · 확인 범위: prerendering 경로에서 요청마다 달라지는 값을 사용할 때 정적 생성 조건을 확인해야 합니다. · 확인일: 2026-08-04