Next.js route 빌드나 렌더링에서 오류가 나요
Next.js route에서 빌드·렌더링 오류가 발생할 때 오류 원문과 route 동작을 확인해 다음 Problem 문서를 선택합니다.
빠른 답변
Next.js route 오류는 오류 원문, 발생한 route, 정적·동적 렌더링 의도와 배포 버전을 함께 기록해야 합니다. `useSearchParams`, `cookies()`·`headers()`, `notFound()` 사용 여부에 따라 확인 경로가 달라집니다.
이 가이드가 맞는 경우
- 애플리케이션 오류 메시지
- 빌드 성공, 배포 실패
상황별 다음 단계
호스팅사·개발자에게 전달할 내용
변경 전 기록
- 오류 원문, route URL, Next.js·Node.js 버전, 배포 commit과 발생 시각을 전달합니다.
- 정적·동적 렌더링 의도와 최근 route·환경 변수·의존성 변경을 기록합니다.
- 인증 토큰, 쿠키, 개인정보와 비밀 환경 변수 값은 전달하지 않습니다.
알아둘 점
이 가이드는 Next.js route에서 오류가 발생했을 때 로그·route·렌더링 방식을 기준으로 다음 Problem을 고릅니다. 오류 원문과 다른 문서의 조치를 섞지 않습니다.
먼저 기록할 것
- 오류 원문과 route URL을 기록합니다.
- Next.js·Node.js 버전, 배포 commit과 최근 route 변경을 기록합니다.
- 해당 route가 정적 생성인지 요청 시 서버 렌더링인지 확인합니다.
상황별 다음 단계
Missing Suspense boundary with useSearchParams라면 Missing Suspense boundary with useSearchParams를 확인합니다.Dynamic server usage: Route used cookies() or headers()라면 Dynamic server usage: Route used cookies() or headers()를 확인합니다.NEXT_NOT_FOUND라면 NEXT_NOT_FOUND를 확인합니다.
오류 문구가 다르면 원문과 최소 재현 route를 보존한 뒤 다른 Next.js Problem을 선택합니다. 해결 여부는 빌드 성공만으로 판단하지 말고 실제 URL 요청으로 확인합니다.
참고 자료
Next.js Error Messages (새 창에서 열림)
Next.js · 공식 자료 · 확인 범위: Next.js 오류 문구와 route·렌더링 맥락을 공식 오류 문서에서 확인합니다. · 확인일: 2026-07-28