최근 Next.js 프로젝트를 진행하면서 무한 로딩과 빌드 실패 현상으로 인해 예상보다 많은 시간을 소비했습니다.
오류 메시지:
Error: Static page generation for /api/file-upload is still timing out after 3 attempts.
처음에는 단순한 API 오류로 생각했지만, 원인은 매우 단순하고 구조적인 충돌이었습니다. 바로 route.ts와 page.tsx가 같은 경로에 존재하고 있었던 것입니다.
🧩 문제 상황 요약
- 경로: /app/api/file-upload/
- 구성:
- page.tsx: 파일 업로드 UI를 렌더링하는 브라우저 페이지
- route.ts: 파일 업로드 요청을 처리하는 API 핸들러
Next.js App Router 구조에서는 같은 폴더에 page.tsx와 route.ts가 공존할 수 없습니다. 이 둘이 동시에 존재할 경우 Next.js는 해당 경로(/api/file-upload)를 정적으로 생성하려다 충돌하게 됩니다.
❗️ 증상
- 개발 서버 실행 시 무한 로딩 또는 랜덤한 오류 발생
- npm run build 시 아래와 같은 에러 발생:
You cannot have two parallel pages that resolve to the same path. Please check /api/file-upload/page and /api/file-upload/route.
- route.ts에서 느린 처리나 fetch 요청이 있을 경우, 빌드 타임에 다음과 같은 타임아웃 오류 발생:
Static page generation for /api/file-upload is still timing out after 3 attempts.
🔍 원인 분석
Next.js App Router의 규칙에 따르면:
- route.ts → API 요청 처리 (GET, POST 등)
- page.tsx → 브라우저 페이지 렌더링
이 두 파일이 같은 디렉터리에 존재하면 Next.js는 정적 페이지 생성 과정에서 혼란을 겪습니다. 특히 route.ts에 fetch 요청이나 대기 시간이 긴 로직이 포함되어 있을 경우, 정적 생성 타임아웃이 발생하며 빌드가 실패합니다.
🛠️ 해결 방법
✅ 1. 디렉터리 구조 정리(핵심)
- app/api/file-upload/route.ts: API 전용으로 유지
- app/file-upload/page.tsx: 페이지 전용 디렉터리로 이동
API와 UI는 서로 다른 경로에 분리하는 것이 안전합니다.
✅ 2. 캐시 삭제 후 재빌드
rm -rf .next .turbo
npm run build
캐시에 남아 있던 충돌 정보가 문제를 지속시킬 수 있으므로 완전 삭제 후 다시 빌드해야 합니다.
✅ 3. 정적 생성 방지 설정 (선택적)
export const dynamic = 'force-dynamic'
route.ts 내에 위 설정을 추가하면 정적 생성 시도가 차단되어 빌드 타임아웃을 방지할 수 있습니다.
✨ 내가 얻은 교훈
- App Router를 사용할 때는 디렉터리 구조와 역할 분리가 반드시 필요하다.
- app/api/는 API 전용 디렉터리로 사용하고, UI 컴포넌트는 분리하여 구성해야 한다.
- 단순한 파일 경로 충돌이 무한 로딩과 빌드 실패 같은 복합적인 문제로 이어질 수 있다.
- 프로젝트 초기 설계 시 폴더 구조와 Next.js 라우팅 규칙을 숙지하는 것이 중요하다.
이 글이 저처럼 App Router 구조에 익숙하지 않은 분들께 도움이 되길 바랍니다.
Next.js에서 구조적인 실수 하나가 예상치 못한 에러로 이어질 수 있다는 점을 미리 알 수 있다면, 시행착오를 줄일 수 있을것 같습니다.
최근 Next.js 프로젝트를 진행하면서 무한 로딩과 빌드 실패 현상으로 인해 예상보다 많은 시간을 소비했습니다.
오류 메시지:
Error: Static page generation for /api/file-upload is still timing out after 3 attempts.
처음에는 단순한 API 오류로 생각했지만, 원인은 매우 단순하고 구조적인 충돌이었습니다. 바로 route.ts와 page.tsx가 같은 경로에 존재하고 있었던 것입니다.
🧩 문제 상황 요약
- 경로: /app/api/file-upload/
- 구성:
- page.tsx: 파일 업로드 UI를 렌더링하는 브라우저 페이지
- route.ts: 파일 업로드 요청을 처리하는 API 핸들러
Next.js App Router 구조에서는 같은 폴더에 page.tsx와 route.ts가 공존할 수 없습니다. 이 둘이 동시에 존재할 경우 Next.js는 해당 경로(/api/file-upload)를 정적으로 생성하려다 충돌하게 됩니다.
❗️ 증상
- 개발 서버 실행 시 무한 로딩 또는 랜덤한 오류 발생
- npm run build 시 아래와 같은 에러 발생:
You cannot have two parallel pages that resolve to the same path. Please check /api/file-upload/page and /api/file-upload/route.
- route.ts에서 느린 처리나 fetch 요청이 있을 경우, 빌드 타임에 다음과 같은 타임아웃 오류 발생:
Static page generation for /api/file-upload is still timing out after 3 attempts.
🔍 원인 분석
Next.js App Router의 규칙에 따르면:
- route.ts → API 요청 처리 (GET, POST 등)
- page.tsx → 브라우저 페이지 렌더링
이 두 파일이 같은 디렉터리에 존재하면 Next.js는 정적 페이지 생성 과정에서 혼란을 겪습니다. 특히 route.ts에 fetch 요청이나 대기 시간이 긴 로직이 포함되어 있을 경우, 정적 생성 타임아웃이 발생하며 빌드가 실패합니다.
🛠️ 해결 방법
✅ 1. 디렉터리 구조 정리(핵심)
- app/api/file-upload/route.ts: API 전용으로 유지
- app/file-upload/page.tsx: 페이지 전용 디렉터리로 이동
API와 UI는 서로 다른 경로에 분리하는 것이 안전합니다.
✅ 2. 캐시 삭제 후 재빌드
rm -rf .next .turbo
npm run build
캐시에 남아 있던 충돌 정보가 문제를 지속시킬 수 있으므로 완전 삭제 후 다시 빌드해야 합니다.
✅ 3. 정적 생성 방지 설정 (선택적)
export const dynamic = 'force-dynamic'
route.ts 내에 위 설정을 추가하면 정적 생성 시도가 차단되어 빌드 타임아웃을 방지할 수 있습니다.
✨ 내가 얻은 교훈
- App Router를 사용할 때는 디렉터리 구조와 역할 분리가 반드시 필요하다.
- app/api/는 API 전용 디렉터리로 사용하고, UI 컴포넌트는 분리하여 구성해야 한다.
- 단순한 파일 경로 충돌이 무한 로딩과 빌드 실패 같은 복합적인 문제로 이어질 수 있다.
- 프로젝트 초기 설계 시 폴더 구조와 Next.js 라우팅 규칙을 숙지하는 것이 중요하다.
이 글이 저처럼 App Router 구조에 익숙하지 않은 분들께 도움이 되길 바랍니다.
Next.js에서 구조적인 실수 하나가 예상치 못한 에러로 이어질 수 있다는 점을 미리 알 수 있다면, 시행착오를 줄일 수 있을것 같습니다.
