Next.js could not validate that a segment in your UI has instant navigation

증상

개발 환경의 Dev overlay에 Next.js could not validate that a segment in your UI has instant navigation 메시지가 표시됩니다. 원문은 프리렌더링 중 route tree의 segment가 렌더링에서 누락되어 Next.js가 instant navigation 검증을 실행할 수 없다고 설명합니다.

확인

1. 해당 route를 개발 환경에서 열고 Dev overlay에 Next.js could not validate that a segment in your UI has instant navigation이 표시되는지 확인합니다.
2. 레이아웃의 출력에 {children} 또는 사용하는 parallel route slot prop이 포함되는지 확인합니다.
3. 수정 후 같은 route로 이동해 insight가 더 이상 표시되지 않는지 확인합니다.
4. 페이지가 즉시 의미 있는 UI를 표시하고, <Suspense> fallback이 스트리밍되는 영역만 덮는지 확인합니다.

조치

누락된 segment 렌더링

segment가 render tree의 일부여야 한다면 segment를 소유한 layout이 {children} 또는 parallel route slot prop을 렌더링하도록 수정합니다. 레이아웃이 인증 상태에 따라 다른 내용을 표시하더라도 두 분기에서 {children}을 렌더링하고 조건 처리는 child segment 안에서 수행합니다.

인증 또는 guard 검사는 layout이 아니라 page 또는 slot 수준으로 이동할 수 있습니다. layout은 항상 {children}을 렌더링하고, 각 page가 내용을 렌더링할지 또는 redirect할지 결정합니다.

parallel route가 누락된 경우에는 layout에서 slot prop을 렌더링합니다. 특정 상태에서 숨겨야 한다면 layout에서 prop을 생략하지 말고 slot 자체의 page 안에서 조건을 처리합니다.

검증 제외

특정 상태에서 segment를 의도적으로 렌더링하지 않는다면 누락된 segment의 page 또는 layout 파일에 export const instant = false를 추가합니다. 이 설정은 해당 segment의 instant-navigation 검증만 건너뛰며 prerendering을 비활성화하지 않습니다.

주의사항

instant = false를 설정하면 해당 segment를 막을 수 있는 문제가 개발 중 검출되지 않을 수 있습니다. layout이 조기에 반환되어 {children}을 렌더링하지 않으면 하위 subtree 전체가 누락될 수 있습니다. Client Component가 SSR 중 null을 반환하는 경우에는 해당 Client Component 위에 <Suspense> boundary를 사용해야 합니다.

segment를 render tree에 포함하면 동적 데이터가 있는 segment에는 자체 <Suspense> boundary 또는 caching strategy가 필요할 수 있습니다.