Amplify에서 required-server-files.json을 찾지 못함
Next.js 빌드는 성공했지만 AWS Amplify가 배포 산출물에서 서버 실행 메타데이터 파일을 찾지 못해 배포가 중단된 상태입니다.
핵심 답변
이 오류는 Amplify가 서버 실행 방식의 Next.js 산출물을 기대하지만 지정된 baseDirectory에서 필요한 메타데이터를 찾지 못했음을 뜻합니다. Next.js output 방식, Amplify 프레임워크 유형, buildPath 기준 baseDirectory, 모노리포 appRoot를 같은 기준으로 확인해야 합니다.
상세 설명
이 오류는 AWS Amplify Hosting이 지정된 산출물 경로에서 Next.js 서버 실행 메타데이터를 찾지 못했을 때 발생합니다. 빌드 성공과 배포 성공은 같은 상태가 아닙니다.
next build가 끝났더라도 Amplify가 기대하는 위치에 배포 파일이 없으면 배포는 실패합니다.
먼저 구분할 값
| 설정·파일 | 의미 |
|---|---|
output | Next.js가 정적 파일 또는 서버 실행 파일을 만드는 방식 |
buildPath | Amplify가 빌드 명령을 실행하는 기준 위치 |
baseDirectory | Amplify가 배포 파일을 찾는 위치 |
appRoot | 모노리포 안에서 애플리케이션을 식별하는 위치 |
정적 HTML 위치인 out과 Amplify의 Next.js 배포 입력인 .next는 용도가 다를 수 있습니다. 세부 파일 구성은 Next.js 빌드 산출물에서 확인합니다.
모노리포 설정 예시
applications:
- appRoot: apps/web
frontend:
buildPath: /
artifacts:
baseDirectory: apps/web/.next
오류 메시지만 보고 산출물 경로를 바꾸지 않습니다. 실제 baseDirectory와 out의 용도를 확인한 뒤 배포 산출물 체크리스트를 실행합니다.
현재 증상
- build-succeeded-deploy-failed
- required-server-files-missing
확인 순서
- Next.js 설정의 output 값이 정적 export인지 서버 실행 방식인지 확인합니다.
- Amplify에 선택된 프레임워크 유형이 실제 output 방식과 일치하는지 확인합니다.
- amplify.yml의 baseDirectory가 buildPath 기준 실제 산출물 경로인지 확인합니다.
- appRoot와 AMPLIFY_MONOREPO_APP_ROOT가 동일한 애플리케이션 경로인지 확인합니다.
- 동일한 빌드 명령을 로컬에서 실행해 .next와 out의 생성 파일을 확인합니다.
주의할 조치
- 빌드 성공 메시지만 보고 배포 산출물이 올바르다고 단정하지 않습니다.
- 정적 export와 서버 실행 배포의 산출물 경로를 임의로 혼합하지 않습니다.
Amplify Next.js 배포 산출물 확인
재배포 전에는 Next.js output 방식, 실제 생성 디렉터리, Amplify 프레임워크 유형, buildPath 기준 baseDirectory, appRoot 환경 변수를 같은 배포 방식에 맞춰 확인해야 합니다.
- Next.js output 방식과 Amplify 프레임워크 유형이 일치합니다.
- 로컬 빌드에서 예상한 .next 또는 out 산출물이 생성됩니다.
- baseDirectory가 buildPath 기준 실제 산출물 위치를 가리킵니다.
- appRoot와 AMPLIFY_MONOREPO_APP_ROOT 값이 같습니다.
- 재배포 로그에서 산출물 수집 이후 배포 단계가 완료됩니다.
근거와 출처
확인 범위: amplify-nextjs-output-directory, static-and-server-deployment-settings · 확인일: 2026-07-22
확인 범위: app-root, build-path, base-directory · 확인일: 2026-07-22