Dynamic server usage: Route used cookies() or headers()

이 오류가 뜻하는 것

동적 API를 사용한 경로를 정적으로 생성하려고 할 때 표시되는 Next.js 오류입니다.

이 문서는 화면이나 로그의 원문을 식별하고 다음 확인 순서를 제시합니다. 오류 문구만으로 운영 환경의 단일 원인을 확정하지 않습니다.

확인 절차

1. 실패한 명령과 개발 서버 또는 빌드 로그의 첫 오류를 기록합니다.
2. package.json의 프레임워크 버전과 lockfile을 확인합니다.
3. 문제가 발생한 import, route 또는 export의 실제 파일 경로와 대소문자를 비교합니다.

해결 순서

1. 오류가 가리키는 파일, export, route를 실제 저장소에서 확인합니다.
2. 경로 대소문자와 패키지 버전을 고친 뒤 lockfile을 유지한 상태로 개발 서버 또는 빌드를 다시 실행합니다.
3. 같은 오류가 남으면 프레임워크가 출력한 원본 스택과 최소 재현 파일을 보존합니다.

주의

• 운영 중인 데이터, 권한, 포트, 인증서와 배포 대상을 한 번에 변경하지 않습니다.
• 수정 전 오류 원문, 실행 명령, 로그 시각과 관련 버전을 보관합니다.
• 공식 문서가 설명하지 않는 환경별 원인은 재현 결과와 해당 플랫폼 문서를 추가로 확인합니다.

공식 근거

• Next.js Error Messages (새 창에서 열림)

진단과 해결 순서

1. 오류 로그가 가리키는 route와 cookies()·headers() 호출 위치를 함께 기록합니다.
2. 해당 route가 빌드 시 정적으로 생성되는지, 요청 시 서버에서 렌더링되는지 빌드 결과와 설정으로 확인합니다.
3. 정적 페이지가 목적이면 요청별 API 사용을 정적 입력으로 바꿀 수 있는지 검토합니다.
4. 요청별 데이터가 목적이면 동적 렌더링 경로로 운영할지 결정하고, 변경 후 빌드와 실제 요청을 각각 재검사합니다.

정적·동적 선택은 배포 비용과 캐시 동작에도 영향을 줄 수 있으므로 오류 문구만 보고 설정을 일괄 변경하지 않습니다.