react 18+ · JavaScript
오류 문구
Hydration failed because the initial UI does not match what was rendered on the server
무슨 뜻인가
서버가 만들어 보낸 HTML과 브라우저가 첫 렌더에서 만든 결과가 달라 React가 둘을 이어 붙이지 못했다는 뜻입니다. 렌더 안에서 new Date()나 Math.random()을 쓰거나 localStorage를 읽거나 window의 폭에 따라 다르게 그리면, 서버와 브라우저의 답이 다를 수밖에 없습니다 — <p> 안에 <div>를 넣은 것처럼 브라우저가 태그를 고쳐 버리는 경우도 같은 결과가 됩니다. 첫 렌더에서는 서버와 같은 것을 그리고, 달라지는 부분은 useEffect가 돈 뒤에 바꾸는 것이 정석입니다. 그 대가로 그 부분은 잠깐 늦게 나타나고, 서버가 만든 HTML에는 담기지 않습니다. React 19에서는 같은 상황이 "the server rendered HTML didn't match the client"로 적히고, 어느 쪽이 달랐는지 diff까지 보여 줍니다.
고치는 명령
한 줄 명령으로 끝나지 않습니다. 설명에 무엇을 봐야 하는지 적어 두었습니다.
- 내는 도구
- react 18+
- JavaScript
- 15
브라우저와 node의 오류는 대개 무엇이 잘못되었는지만 알려 주고 왜 그 값이 그렇게 되었는지는 알려 주지 않아서 — undefined를 읽었다, 함수가 아니었다, JSON이 아니었다 — 고칠 자리는 터진 줄이 아니라 그 값을 만든 위쪽에 있고, ?.와 기본값으로 그 줄만 조용하게 만들면 같은 문제가 더 먼 곳에서 더 알아보기 어려운 꼴로 다시 나타납니다.
오류 문구를 읽는 법
- 첫 줄부터 읽습니다. 아래로 갈수록 도구 내부 이야기이고, 정작 원인은 맨 위에 적혀 있습니다.
- 파일 이름과 줄 번호가 있으면 거기가 시작점입니다 — 스택의 가장 위가 아니라, 내가 쓴 파일이 나오는 가장 위 줄입니다.
- 문구를 그대로 검색합니다. 다만 내 경로와 변수 이름은 지웁니다 — 그 부분이 검색을 방해합니다.
- 같은 문구가 도구 판마다 다르게 나옵니다. 검색 결과가 안 맞으면 판 번호를 함께 넣어 봅니다.
- 고치는 명령을 붙여 넣기 전에 그 명령이 무엇을 버리는지 확인합니다. 되돌릴 수 없는 것이 섞여 있습니다.
자주 묻는 질문
Q. Hydration failed because the initial UI does not match what was rendered on the server 는 무슨 뜻인가요?
서버가 만들어 보낸 HTML과 브라우저가 첫 렌더에서 만든 결과가 달라 React가 둘을 이어 붙이지 못했다는 뜻입니다. 렌더 안에서 new Date()나 Math.random()을 쓰거나 localStorage를 읽거나 window의 폭에 따라 다르게 그리면, 서버와 브라우저의 답이 다를 수밖에 없습니다 — <p> 안에 <div>를 넣은 것처럼 브라우저가 태그를 고쳐 버리는 경우도 같은 결과가 됩니다. 첫 렌더에서는 서버와 같은 것을 그리고, 달라지는 부분은 useEffect가 돈 뒤에 바꾸는 것이 정석입니다. 그 대가로 그 부분은 잠깐 늦게 나타나고, 서버가 만든 HTML에는 담기지 않습니다. React 19에서는 같은 상황이 "the server rendered HTML didn't match the client"로 적히고, 어느 쪽이 달랐는지 diff까지 보여 줍니다.
Q. 어떻게 고치나요?
한 줄 명령으로 끝나지 않습니다. 위 설명에서 무엇을 봐야 하는지 적어 두었습니다.
Q. 어느 도구가 내는 오류인가요?
react 18+입니다. JavaScript 갈래에 있고, 문구는 15낱말입니다.