CustomerError: Can't find required-server-files.json in build output directory

이 오류는 AWS Amplify Hosting이 지정된 산출물 경로에서 Next.js 서버 실행 메타데이터를 찾지 못했을 때 발생합니다. 빌드 성공과 배포 성공은 같은 상태가 아닙니다.

next build가 끝났더라도 Amplify가 기대하는 위치에 배포 파일이 없으면 배포는 실패합니다.

먼저 구분할 값

정적 HTML 위치인 out과 Amplify의 Next.js 배포 입력인 .next는 용도가 다를 수 있습니다. 세부 파일 구성은 Next.js 빌드 산출물에서 확인합니다.

모노리포 설정 예시

applications:  - appRoot: apps/web    frontend:      buildPath: /      artifacts:        baseDirectory: apps/web/.next

오류 메시지만 보고 산출물 경로를 바꾸지 않습니다. 실제 baseDirectory와 out의 용도를 확인한 뒤 배포 산출물 체크리스트를 실행합니다.

설정 조합 확인

서버 실행 방식의 Next.js 앱이면 Amplify가 서버 실행 파일이 포함된 .next 산출물을 찾도록 설정해야 합니다. 정적 export를 선택한 앱이면 out을 정적 산출물로 사용하는 방식과 Amplify의 호스팅 유형이 함께 맞아야 합니다. 한 항목만 바꾸기보다 next.config.*, amplify.yml, Amplify 콘솔의 프레임워크 설정, 실제 빌드 로그의 출력 경로를 같은 기준으로 대조하세요.

모노리포에서는 appRoot가 애플리케이션 위치를, buildPath가 명령 실행 기준을, baseDirectory가 결과 탐색 기준을 정합니다. 따라서 apps/web/.next처럼 보이는 경로도 어느 기준에서 해석되는지 확인하지 않으면 같은 오류가 반복될 수 있습니다.

수정 후 확인

변경 후에는 같은 커밋과 같은 빌드 명령으로 다시 빌드하고, 빌드 로그에서 Amplify가 실제로 업로드한 산출물 경로를 확인합니다. 배포가 성공한 뒤에는 한 페이지를 열어 SSR 응답과 정적 자산이 모두 정상인지 확인합니다. 이전 실패 로그와 변경한 값, 재배포 시각을 함께 보관하면 다음 배포에서 같은 경로 혼동을 줄일 수 있습니다.

원인 분포

[Observation] 관측된 사례 기준으로 확인된 원인은 다음 세 유형입니다.

• Next.js의 SSR·SSG 형식과 Amplify의 배포 설정 불일치: SSG 앱의 out 경로 또는 SSR 앱의 .next 경로 설정 문제입니다.
• 모노리포에서 실제 애플리케이션 경로와 Amplify의 appRoot 불일치입니다.
• Nx 모노리포에서 Next.js 의존성 탐지로 Vite 앱을 Next.js SSR로 잘못 판별한 경우입니다.

[Observation] 이 사례 수는 실제 발생 빈도를 의미하지 않습니다.

오진 함정

[Observation] required-server-files.json 누락은 Next.js SSR 산출물 자체의 문제로만 단정할 수 없습니다.

• SSG 앱을 SSR 앱으로 판별했을 가능성이 있습니다.
• Vite 앱이 모노리포 내부의 Next.js 의존성 때문에 Next.js SSR로 판별될 수 있습니다.
• 모노리포에서는 빌드가 성공했더라도 Amplify의 appRoot와 실제 .next 산출물 경로가 다르면 배포가 실패할 수 있습니다.

[Hypothesis] 오류 파일의 존재 여부를 확인하기 전에 프레임워크 판별 결과와 애플리케이션 루트 경로를 먼저 대조하면 오진을 줄일 수 있습니다.

환경 매트릭스

진단 순서

[Hypothesis] 다음 순서로 확인하는 것이 세 사례의 원인과 직접 연결됩니다.

1. 배포 대상이 Next.js SSG, Next.js SSR, Vite 중 무엇인지 확인합니다.
2. Amplify가 선택한 프레임워크가 실제 애플리케이션과 일치하는지 확인합니다.
3. Next.js라면 output: 'export' 사용 여부에 따라 out 또는 .next가 배포 기준 경로인지 확인합니다.
4. 모노리포라면 appRoot가 실제 앱 디렉터리와 일치하는지 확인하고, 해당 경로에서 next build가 실행되는지 확인합니다.
5. Vite 앱에 Next.js 의존성이 함께 있는 경우 프레임워크 오판 가능성을 확인하고, 사례에서 사용한 의존성 위치 조정을 검토합니다.