vercel 배포 오류는 Deployments 화면에서 실패한 배포를 열고, 빌드 로그에서 빨간 「Error」 줄을 찾아 그보다 몇 줄 위를 읽으면 원인이 보입니다. 맨 마지막 Error 줄은 「빌드 명령이 실패했다」는 결과만 알려 주는 경우가 많기 때문입니다.
2026년 10월 23일 Vercel 공식 문서(Troubleshooting Build Errors · Accessing Build Logs · Error List 등)를 직접 읽고, 빌드 로그 읽는 순서와 문서에 적힌 흔한 원인만 모았습니다. 메뉴 이름은 공식 문서 글자 그대로 적었습니다.
1. vercel 배포 오류, 빌드 로그는 어디서 보나요?
프로젝트의 Deployments 화면에서 봅니다. 빌드는 내가 쓴 코드를 인터넷에 올릴 수 있는 모양으로 바꾸는 과정이고, 빌드 로그는 그동안 화면에 찍힌 기록입니다. 공식 문서가 안내하는 순서는 이렇습니다.
- Vercel 대시보드에서 프로젝트를 고르고 옆 메뉴의
Deployments를 엽니다 - 배포 목록에서 오류 표시가 붙은 배포를 고릅니다
- 배포 화면의
Deployment Details에서Building칸을 펼쳐 로그를 엽니다 - 아래로 내리며 빨간색으로 「Error」가 적힌 부분을 찾습니다
로그에서 노란색은 경고, 빨간색은 오류입니다. 빌드 로그는 배포마다 기간 제한 없이 보관되고, 전체 크기가 4MB를 넘으면 잘립니다.
2. 마지막 Error 줄보다 몇 줄 위를 읽습니다
Error는 로그에 한 번이 아니라 여러 번 나올 수 있습니다. 공식 문서는 이렇게 짚습니다.
In many cases, the last mention is not indicative like in the example below where it says yarn run build exited with 1.
마지막 Error 줄은 많은 경우 원인을 가리키지 않는다는 뜻입니다. 문서의 예에서도 진짜 원인은 그보다 몇 줄 위의 다른 오류에 적혀 있었습니다. 위쪽에 Error가 없더라도 그 근처 출력이 문제 자리를 알려 주는 경우가 많다고 합니다.
Vercel에 다시 올리기 전에 내 컴퓨터에서 빌드 명령(Next.js라면 npm run build)을 먼저 돌려 보면, 내 코드나 설치 꾸러미 문제를 바로 잡을 수 있습니다. 공식 문서도 이 순서를 권합니다.
3. 로그가 아예 없는 빌드 실패
빌드가 시작조차 못 하면 로그 없이 실패합니다. 이때는 Building 칸을 열 수 없고, 화면 위에 오류 메시지 창이 뜹니다. 문서가 든 예는 네 가지입니다.
- 잘못된
vercel.json설정 파일을 올렸을 때 - Ignored Build Step(조건에 따라 빌드를 건너뛰는 설정)을 쓸 때
- 팀 멤버가 아닌 사람이 커밋(바뀐 코드 저장 기록)을 올렸을 때
- 연결한 Marketplace 연동(데이터베이스 등) 준비가 빌드 전에 실패했을 때
마지막 경우는 Deployment Details의 Provisioning Integrations 단계에 오류 표시가 붙습니다. 그 연동 업체 쪽 문제를 고친 뒤 다시 배포(Redeploy)하면 됩니다.
4. 빌드 명령과 출력 폴더가 맞는지 봅니다
빌드 명령은 Vercel이 프레임워크에 맞춰 자동으로 정합니다. 프레임워크를 알아보지 못하면 Other 가 선택되고 빌드 명령을 직접 적어야 합니다. 출력 폴더는 빌드 결과물이 담기는 폴더로, Vercel은 이 폴더 안의 것만 내보냅니다.
Error List 문서의 Missing public directory 오류는 출력 폴더가 없거나, 비었거나, 폴더가 아닐 때 납니다. 문서가 권하는 확인 순서는 이렇습니다.
- 프로젝트 설정의 출력 폴더(Output Directory)가 맞게 적혔는지 봅니다
- 맞다면 빌드 명령(Build Command)이나 루트 폴더(Root Directory)를 봅니다
- 내 컴퓨터에서 빌드 명령을 돌려 그 폴더에 파일이 생기는지 봅니다
5. Node.js 버전과 환경 변수도 확인합니다
2026년 10월 23일 Vercel 문서 기준으로 고를 수 있는 Node.js 버전은 24.x(기본)와 22.x입니다. 내 컴퓨터에서는 되는데 Vercel에서만 실패하면 두 곳의 버전이 같은지 봅니다.
버전은 프로젝트의 Settings → Build and Deployment → Node.js Version 에서 바꿉니다. 바꾼 버전은 새 배포부터 쓰입니다.
환경 변수는 API 키처럼 코드 밖에 두는 설정값입니다. 공식 문서는 환경 변수를 바꾼 뒤에는 새 배포를 만들어야 적용된다고 적었습니다. 값을 넣고 다시 배포하지 않으면 예전 값으로 빌드됩니다.
6. 한도에 걸려 취소된 빌드
빌드가 플랫폼 한도에 걸리면 취소되고, 그 오류가 빌드 로그에 나옵니다. Troubleshooting 문서 표에 적힌 빌드 한도는 이렇습니다(메모리·디스크는 기본 빌드 머신 기준이고, Pro는 더 큰 빌드 머신을 고를 수 있습니다).
- 빌드 시간 최대 45분 — 넘으면 배포 취소
- 빌드 메모리 8192MB — 넘으면 취소
- 디스크 32GB — 넘으면 취소
메모리나 디스크 한도에 닿으면 빌드 로그에 시스템 보고서가 자동으로 붙으니, 코드 오류인지 한도 문제인지는 이 보고서로 먼저 가릅니다. 모든 빌드에서 보고서를 보려면 환경 변수 VERCEL_BUILD_SYSTEM_REPORT=1 을 넣습니다.
정리하면 Vercel 빌드 실패는 이 순서로 읽습니다.
- Deployments → 실패한 배포 → Building 로그를 엽니다
- 마지막 Error 줄보다 몇 줄 위에서 원인을 찾습니다
- 로그가 없으면 화면 위 오류 창과 vercel.json·연동 상태를 봅니다
- 빌드 명령·출력 폴더, Node.js 버전, 환경 변수 순으로 확인합니다
- 45분·메모리·디스크 한도에 걸렸는지 시스템 보고서로 확인합니다
처음 올리는 순서는 vercel 배포 방법, 처음부터 끝까지에, 깃허브 페이지에서 404가 날 때는 깃허브 페이지 배포 안됨, 404 해결 순서에 정리했습니다.
다른 무료 배포 서비스와 비교는 웹사이트 배포 무료, 어디에 올릴까 총정리를 참고하세요.
참고자료 (모두 2026년 10월 23일 확인)
- Vercel 문서 「Troubleshooting Build Errors」 — vercel.com/docs/deployments/troubleshoot-a-build
- Vercel 문서 「Accessing Build Logs」 — vercel.com/docs/deployments/logs
- Vercel 문서 「Error List」 — vercel.com/docs/errors/error-list
- Vercel 문서 「Configuring a Build」 — vercel.com/docs/builds/configure-a-build
- Vercel 문서 「Supported Node.js versions」·「Environments」 — vercel.com/docs/functions/runtimes/node-js/node-js-versions
#Vercel오류 #빌드실패 #Vercel배포 #웹사이트배포 #바이브코딩
