앱이 망가졌을 때 당황하지 않는 세 가지 장면 — 빌드 실패·하얀 화면·되돌리기

세 장면 한눈에

먼저 숨 고르기 — 손님은 아직 «어제 버전»을 보고 있습니다

걱정스러운 직장인이 길게 출력된 오류 기록을 로봇 의사에게 보여 주고, 로봇 의사가 빨간 한 줄을 가리키는 그림. 옆 노트북은 하얀 화면 — 오류 기록은 «진료 기록지». 내가 해석할 필요 없이 통째로 AI 의사에게 보여 주면 됩니다. 의사는 빨간 한 줄을 찾아냅니다.

Vercel 배포 목록 — Ready, Error, Ready, Ready 네 줄, 두 번째 Error 줄에 빨간 네모 — 연습용 프로젝트의 배포 기록. 아래부터 정상(Ready) → 정상 → **빌드 실패(Error)** → 배포는 됐지만 화면이 하얀 버전(Ready). 네 번의 «올리기»가 그대로 남아 있습니다.

증상	뜻	손님 화면은?	할 일
① Vercel에 빨간 Error	포장(빌드)하다 실패. 새 버전이 아예 안 올라감	어제 버전 그대로 — 안전	오류 글씨 복사 → AI에게
② Ready인데 화면이 하얌	올라가긴 했는데 화면을 그리다 멈춤	하얀 화면 — 급함	먼저 ③으로 되돌리고, 그다음 고치기
③ 급히 되돌리기	손님이 보는 진열대만 이전 버전으로 교체	몇 초 만에 복구	Vercel Instant Rollback

장면 ① 빨간 Error

«Build Failed» — 걱정 말고, 빨간 글씨만 복사

연습용 페이지에 «style.css 파일도 같이 올려줘»라는 설정을 넣었는데, 정작 그 파일은 없었습니다. 실제 바이브 코딩에서도 아주 흔한 실수입니다(AI가 만들겠다고 해 놓고 빠뜨린 파일).

Vercel 배포 상세 — Build Failed 카드에 Command npm run build exited with 1, 아래 Deploy Logs의 빨간 Error: ENOENT 줄에 빨간 네모 — Error 줄을 누르면 나오는 배포 상세. 위 **Build Failed** 카드가 «실패했다»는 요약, 아래 **Deploy Logs**의 분홍 줄들이 «왜» 실패했는지입니다.

Deploy Logs 확대 — Error: ENOENT: no such file or directory, copyfile 'style.css' -> 'dist/style.css' 줄에 빨간 네모 — 핵심은 첫 분홍 줄: **«no such file or directory, 'style.css'»** = «style.css라는 파일이 없다». 영어를 몰라도 됩니다 — 이 분홍 덩어리를 **통째로 복사**해서 AI에게 붙여 넣으면 끝.

Error가 떠도 손님은 모릅니다

빌드에 실패하면 새 버전은 진열대에 올라가지 않습니다. 손님에게는 마지막으로 성공한 버전이 계속 보입니다. 그래서 빨간 Error는 «급한 사고»가 아니라 «다시 하면 되는 실패»입니다.

장면 ② 하얀 화면

«Ready» 초록불인데 화면이 텅 — 진짜 급한 건 이쪽

두 번째 고장은 더 얄궂습니다. 코드에 오타 하나(document → documnet)를 넣었습니다. 포장은 문제없이 끝나서 Vercel은 초록불 Ready를 띄웠지만, 실제 주소를 열면 아무것도 안 보입니다.

교육 안내 페이지 주소를 열었지만 완전히 하얀 화면 — vibe-broken-demo.vercel.app — 제목도, 일시도, 장소도 없는 하얀 화면. 손님이 지금 이걸 보고 있습니다.

먼저 되돌리기 — 원인 찾기보다 손님 화면 복구가 먼저입니다. 바로 아래 «장면 ③».
F12로 진료 기록 보기 — 하얀 화면에서 키보드 F12(맥은 ⌥⌘I) → 위쪽 Console(콘솔) 탭. 빨간 글씨가 보입니다. 이번 경우엔 «documnet is not defined»(documnet이라는 건 없다) — 오타가 그대로 찍혀 있습니다.
빨간 글씨 복사 → AI에게 — «이 오류 때문에 화면이 하얘, 고쳐서 다시 올려줘».

요령 F12 화면이 낯설면 그냥 화면 전체를 캡처해서 AI에게 붙여 넣어도 됩니다. 요즘 코딩 AI는 사진 속 오류 글씨도 읽습니다. 단, 캡처에 열쇠(API 키)가 찍히지 않았는지 확인하세요(«바이브 04»).

장면 ③ 되돌리기

Instant Rollback — 손님 진열대만 «어제»로

가게 앞에서 깨진 간판을 떼고 뒷방 선반에 보관된 이전 간판을 다시 거는 사람, 가게 위로 빨간 되감기 화살표 — Vercel은 예전 간판(배포)을 전부 뒷방에 보관합니다. 깨진 간판을 떼고 어제 간판을 다시 거는 데 몇 초면 됩니다.

Vercel 프로젝트 → Deployments → 마지막으로 잘 되던 줄(초록 Ready) 오른쪽 ⋯
메뉴에서 Instant Rollback → 확인 창에서 «지금(Current) → 이전(Previous)»을 확인하고, 이유를 한 줄 적은 뒤 Continue

Instant Rollback 확인 창 — Current 배포에서 Previous 배포로 되돌리기, 이유 입력 칸, Continue 버튼에 빨간 네모 — 확인 창. 위가 지금 손님이 보는 버전(Current), 아래가 되돌아갈 버전(Previous). 다른 버전으로 가고 싶으면 «Choose another deployment».

되돌린 뒤 다시 보이는 교육 안내 페이지 — 신입사원 입문 교육 안내, 일시, 장소, 신청 인원 24명 — 되돌린 직후의 같은 주소. «신입사원 입문 교육 안내»가 다시 보입니다.

되돌린 뒤의 배포 목록 — 파란 Production 표시가 세 번째 정상 배포 줄로 옮겨 감, 그 표시에 빨간 네모 — 배포 목록에서 파란 **Production** 표시가 예전 정상 버전 줄로 옮겨 갔습니다. 하얀 화면 버전은 지워지지 않고 남아 있어서, 고친 뒤 다시 올리면 됩니다.

되돌리기 다음엔 «자동 배포 멈춤»을 기억하세요

Instant Rollback을 하면 Vercel은 «사람이 직접 고르는 중»으로 보고, 다음 GitHub 업로드를 바로 손님 진열대에 올리지 않을 수 있습니다. 고친 버전을 올린 뒤 Vercel에서 그 배포를 Promote(손님 진열대로 올리기) 하거나, AI에게 «고친 버전이 손님 화면에 반영됐는지 확인해줘»라고 하세요.

오류 글씨 읽는 법

다 읽지 마세요 — 세 군데만

어디를	왜	이번 예에서는
첫 «Error» 줄	진짜 원인. 아래 줄들은 대부분 «어디서 터졌는지» 경로	Error: ENOENT … 'style.css'
파일 이름	어느 파일 문제인지	style.css, build.js
마지막 줄	결과 요약	Command "npm run build" exited with 1 (= 실패로 끝남)

그래도 AI에게는 «통째로»

세 군데를 아는 건 «무슨 일인지 감 잡기»용입니다. AI에게 줄 때는 앞뒤를 자르지 말고 분홍 덩어리 전체를 주세요. 잘라 주면 AI가 엉뚱한 곳을 고칠 수 있습니다.

자주 보는 말 사전

오류 메시지 단골 열 개

이런 말이 보이면	쉬운 뜻
Build Failed / exited with 1	포장 실패. 새 버전이 안 올라감(손님은 어제 버전)
ENOENT / no such file	그런 파일이 없음 — 빠뜨렸거나 이름이 틀림
is not defined	그런 이름이 없음 — 오타이거나 준비 안 된 것
Cannot find module	필요한 부품(패키지)이 설치 안 됨
404 / NOT_FOUND	그 주소에 페이지가 없음
401 / 403 / Permission denied	로그인 안 됨 / 권한 없음 — 열쇠·장부 규칙 문제일 때가 많음
500 / Internal Server Error	주방(서버)에서 사고 — 서버 기록(Logs)을 AI에게
CORS	«다른 가게 주문은 안 받아요» — 주소 허용 목록 문제
Timeout	너무 오래 걸려 포기함
Quota / Rate limit / 429	무료 한도나 요청 횟수 초과 — 잠시 뒤 또는 요금제 확인

AI에게 말하기

명령어 대신, 이렇게 말하세요

AI-01 💬 코딩 에이전트

빨간 Error — 오류 붙여 넣기

Vercel 배포 실패 때

Vercel 배포가 Error로 실패했어. 아래가 Deploy Logs에 나온 빨간 글씨 전체야.
원인을 초보자도 알게 한두 줄로 설명하고, 고쳐서 다시 올린 뒤 Ready가 될 때까지 확인해줘.
(여기에 빨간 글씨를 통째로 붙여 넣기)

AI-02 💬 코딩 에이전트

하얀 화면 — 되돌리고 고치기

Ready인데 화면이 안 보일 때

배포는 Ready로 끝났는데 실제 주소를 열면 화면이 하얗게 나와.
1) 먼저 Vercel에서 마지막으로 잘 되던 배포로 되돌려줘(Instant Rollback 또는 명령 도구로).
2) 그다음 브라우저 콘솔 오류를 확인해서 원인을 찾고, 고친 버전을 올려줘.
3) 고친 버전이 손님 화면(Production)에 실제로 반영됐는지 주소를 열어 확인해줘.

AI-03 💬 코딩 에이전트

어제로 — GitHub 기록 기준 되돌리기

무엇이 망가뜨렸는지 모를 때

오늘 고친 뒤로 앱이 이상해졌는데 어느 수정 때문인지 모르겠어.
GitHub 기록을 보고 마지막으로 잘 되던 커밋을 찾아서, 그 뒤로 바뀐 것을 쉬운 말로 목록으로 보여줘.
내가 고르면 그 상태로 되돌려서 다시 배포해줘. 지운 내용은 나중에 다시 꺼낼 수 있게 기록은 남겨줘.

요령 손님 화면이 급하면 AI-02의 1번(진열대 되돌리기)부터. 창고(GitHub) 정리는 그다음입니다.

다음 편

바이브 코딩 기초 시리즈

편	내용
바이브 01 · 지도	작업실·창고·가게·장부·열쇠
바이브 02 · 배포	GitHub 저장 + Vercel 배포
바이브 03 · 장부	Supabase·구글 시트로 응답 모으기
바이브 04 · 열쇠	API 키가 새는 길과 막는 법
바이브 05 · 망가졌을 때 (지금 글)	빨간 Error · 하얀 화면 · 되돌리기
실전 02 · Codex로 처음부터 끝까지	기초 다섯 편을 한 번에 써 보는 실습

이 글을 만든 방법

2026년 10월 8일, 연습 전용 Vercel 프로젝트(vibe-broken-demo)에 정상 버전·빌드 실패 버전·하얀 화면 버전을 차례로 실제 배포하고, 정상 버전으로 되돌리며 찍었습니다. 실제 서비스에는 영향이 없습니다.