Next.js encountered uncached data in generateMetadata()

오류 의미

Cache Components가 활성화된 상태에서 프리렌더링 중 generateMetadata()가 캐시되지 않은 데이터에 접근하면 이 오류가 발생합니다. 원문에 제시된 접근은 fetch(), 데이터베이스 호출, await connection()입니다. 이때 메타데이터는 차단되지만 나머지 콘텐츠는 프리렌더링될 수 있습니다.

확인

• next dev에서 오류 오버레이를 확인합니다. 오버레이가 실패한 컴포넌트의 파일 경로와 줄 번호를 가리키면 해당 컴포넌트가 오류 위치입니다.
• 빌드에서 확인할 때 next build --debug-prerender 결과를 확인합니다. 이 옵션은 전체 사용자 코드 스택 추적을 제공합니다.
• 특정 경로만 확인할 때 next build --debug-build-paths /dashboard /settings 결과를 확인합니다.

복구 방법

메타데이터를 캐시하는 경우

메타데이터가 외부 소스에서 오지만 요청마다 변경될 필요가 없으면 generateMetadata()의 첫 문장으로 'use cache'를 추가합니다. Next.js는 반환된 메타데이터 객체를 캐시하고 프리렌더링에 포함합니다.

export async function generateMetadata() {  'use cache'  return await cms.getMeta()}

cookies() 또는 headers()를 같은 캐시 범위에서 사용할 수 없습니다. 요청별 값이 필요하면 해당 값을 캐시 범위 밖에서 읽어 인자로 전달하거나 동적 라우트 방식을 사용합니다.

메타데이터를 동적으로 유지하는 경우

페이지의 나머지 콘텐츠가 정적이고 메타데이터만 동적으로 유지하려면 connection()을 호출하고 null을 반환하는 동적 마커를 만든 뒤 <Suspense>로 감쌉니다.

import { Suspense } from 'react'import { connection } from 'next/server'async function DynamicMarker() {  await connection()  return null}export default function Page() {  return (    <>      <article>This article is completely static</article>      <Suspense>        <DynamicMarker />      </Suspense>    </>  )}

동적 마커는 반드시 <Suspense>로 감싸야 합니다. 그렇지 않으면 동적 처리가 상위로 전파되어 같은 차단 라우트 오류가 나타날 수 있습니다.

수정 후 확인

라우트를 다시 로드하고 의미 있는 UI가 즉시 표시되는지 확인합니다. <Suspense> 폴백은 스트리밍되는 영역만 덮어야 합니다. 전체 페이지 본문을 <Suspense>로 감싸 빈 셸만 표시되는 구성은 원문의 검증 목적을 충족하지 않습니다.

참고

검증을 사용하지 않으려면 페이지 또는 레이아웃 파일에 export const instant = false를 추가해 해당 세그먼트의 검증을 해제할 수 있습니다. 전체 앱에서는 next.config의 experimental.instantInsights.validationLevel을 'manual-warning'으로 설정할 수 있습니다.