문제 해결

배포 실패 · 접속 불가 · 프리뷰 오류를 증상별로 좁혀서 해결하는 방법이에요.

뭔가 막혔을 때는 증상별로 좁혀 가면 빨라요.
지금 겪는 상황과 가장 비슷한 제목을 골라 증상 → 원인 → 해결 순서로 따라가세요.

한 가지만 기억하세요. 에러 로그는 요약하지 말고 그대로 Claude Code나 Codex에 붙여넣는 게 원인을 가장 빨리 찾는 길이에요.

배포가 안 돼요

앱을 만들다 실패했어요

증상 — 앱 만들기(부트스트랩)를 하다가 화면에 실패 메시지와 다시 시도 버튼이 떠요.

원인 — 대부분 저장소 이름 · GitHub App 설치 · 주소 형식 문제이고, 무엇이 잘못됐는지 화면 메시지에 그대로 나와요.

해결 — 메시지에 맞는 조치를 한 뒤 다시 시도하면 돼요.

메시지	해결
같은 이름의 저장소가 이미 있어요	Git 저장소 단계로 돌아가 다른 저장소 이름으로 다시 시도
GitHub App 설치가 필요해요	Git 저장소 단계에서 axhub GitHub App 설치를 완료
슬러그 · 서브 도메인 형식 오류	영문 소문자 · 숫자 · 하이픈만 사용
앱 생성에 실패했어요	일시적일 수 있어요 — 잠시 후 다시 시도

배포가 실패로 떠요

증상 — 코드를 GitHub에 올렸는데(push) 배포 탭에 실패가 떴어요.

원인 — 대부분 빌드/시작 명령, 포트, 환경변수, Dockerfile 또는 axhub.yaml(manifest)이 실제 코드와 안 맞는 경우예요.

해결 — 세 명령으로 원인을 좁히고, 자주 나는 원인 표에서 증상을 찾아 고친 뒤 다시 올려요.

세 명령으로 좁히기

<deployment-id>에는 확인하려는 배포의 ID를, <app>에는 앱 이름을 넣어요.

axhub deploy status <deployment-id> --app <app> --json
axhub deploy logs <deployment-id> --app <app> --limit 200
axhub deploy doctor --app <app>

셋은 서로 다른 걸 알려 줘요. 하나만 보면 원인을 놓치기 쉬우니 함께 보세요.

status — 이 배포가 왜 멈췄는지(failure reason)를 알려 줘요.
logs — 실제로 실행되다 난 에러예요. 마지막 에러 줄부터 보면 돼요.
doctor — 배포 자체가 아니라 내 환경을 점검해요. 로그인 상태, 접속 주소(endpoint), 서버 버전이 맞는지 확인해 줘요.

자주 나는 원인 표에서 찾기

배포 로그를 열어 빌드가 어디까지 갔다가 멈췄는지 보고, 아래 표의 왼쪽과 비슷한 증상을 찾아 오른쪽부터 확인하세요.

증상	확인할 것
Dockerfile을 못 찾음	루트에 `Dockerfile`이나 Compose 파일을 둬요. `axhub.yaml`만으로는 부족할 수 있어요(`static` · `dockerfile` 지정 · `pinned`+`start`가 아니면 계속 판정해요). 반대로 Node · Python · Go · Ruby · Java는 자동 감지로 셋 다 없어도 될 수 있어요 (빌드 방법 정하기)
compose 파일을 못 찾음	`build.deploy_method: compose`와 `build.compose_file` 경로
빌드/실행 명령을 모름	`axhub.yaml`에 `build` · `start` 명령을 적어요 (axhub.yaml 레퍼런스)
manifest 형식 · 검증 오류	8 KiB 이하, `runtime.port` 1~~65535, `runtime.entry_service`(compose 전용), `runtime.healthcheck` 값은 `90s`처럼 단위 필수, `ci.timeout` 1~~600, `ci.commands` 최대 10개
환경변수가 없다는 오류	`axhub.yaml`의 `env.required`와 `axhub env list --app <app>`의 Stage가 맞는지 확인 (환경변수 설정하기)
환경변수를 바꿨는데 그대로	환경변수를 바꾸면 다시 배포해야 적용돼요
저장소 · 브랜치를 못 찾음	`axhub apps git status --app <app>`으로 GitHub 연결을 보고, GitHub App 설치 · 저장소 권한과 브랜치(`main`)를 확인
진입 서비스를 못 찾음 (`build.entry_service_not_found`)	`axhub.yaml`의 `runtime.entry_service` 이름이 compose 파일의 서비스와 일치하는지 — 실패 메시지에 실제 서비스 목록이 나와요
진입 서비스에 포트가 없음 (`build.entry_service_has_no_port`)	그 서비스에 `ports:` 또는 `expose:` 선언을 추가 (compose 진입 서비스)
빌드는 됐는데 뜨지 못하고 실패 (`healthcheck.startup_budget_exceeded` · `healthcheck.container_crash`)	앱이 60초 안에 헬스체크에 응답하지 못하면 재시작돼요. 마이그레이션 · 시드를 시작 명령에서 분리하고, 부팅이 오래 걸리면 `axhub.yaml`의 `runtime.healthcheck.start_period`를 올려요 (헬스체크 대기 시간). 코드별 조치는 아래 헬스체크 실패 사유 코드
로그에 `spawn … ENOENT` · `not found` 가 찍히는데 그 파일은 분명히 있음	미리 빌드된 바이너리(workerd · sharp · Prisma 엔진 등)가 Alpine 이미지(musl)에서 실행되지 않는 경우예요. Dockerfile 의 `FROM node:22-alpine` 을 `FROM node:22-slim` 으로 바꿔요. `axhub import` 가 만들어 준 Dockerfile 도 내 저장소 파일이라 고쳐도 돼요

고치고 다시 올리기

고친 다음 커밋을 GitHub에 다시 올리고(push), 새 배포가 도는 것을 확인하면 돼요. 배포 상태 값 · 로그 읽는 법 · 되돌리기의 자세한 절차는 배포 관리에 있어요.

헬스체크 실패 사유 코드

증상 — 빌드는 끝났는데 배포가 실패로 떴고, 실패 사유 코드가 healthcheck.로 시작해요.

원인 — 새 컨테이너가 뜨는 단계에서 막힌 거예요. 코드가 어디서 막혔는지 갈라 줘요. 실패 사유는 앱 콘솔의 배포 탭이나 axhub deploy status <deployment-id> --app <app> --json에 나와요.

해결 — 코드에 맞는 조치를 하고 다시 올려요.

코드	뜻	할 일
`healthcheck.startup_budget_exceeded`	헬스체크 대기 시간(문구에 초 단위로 나와요) 안에 첫 응답이 없어 플랫폼이 재시작했어요. 앱은 살아 있었어요	`runtime.healthcheck.start_period`를 올리거나, 마이그레이션 · 시드를 시작 명령에서 빼서 부팅을 줄여요 (헬스체크 대기 시간)
`healthcheck.container_crash`	컨테이너가 스스로 종료했거나 메모리를 넘겼어요	앱 로그의 마지막 에러 줄과 리소스 설정을 봐요. 마지막 줄이 `spawn … ENOENT` 면 베이스 이미지가 앱 의존성과 안 맞는 경우예요(위 원인 표). 대기 시간 초과인데 이 코드로 보이면 새 배포로 재현하세요 — 오래된 배포는 판정 근거가 지워져 이렇게 보일 수 있어요
`healthcheck.image_pull_failed`	컨테이너 이미지를 가져오지 못했어요	이미지 이름과 레지스트리 권한
`healthcheck.container_config_error`	환경변수 · 시크릿 · 컨테이너 설정이 잘못됐어요	`axhub env list --app <app>`으로 이름과 Stage 확인
`healthcheck.rollout_timeout`	시간 안에 안정되지 않았어요	앱 로그와 `health_path` 응답을 확인하고 다시 배포
`healthcheck.capacity_wait_timeout`	클러스터에 자리가 나지 않았어요. 앱 문제가 아니에요	잠시 후 다시 배포
`healthcheck.deployment_cancelled`	배포를 중간에 멈췄어요	준비되면 새 배포
`healthcheck.targets_unresolved` · `healthcheck.diagnosis_unavailable`	플랫폼이 배포 상태를 끝까지 읽지 못했어요	새 배포를 시작

재시작된 컨테이너가 60초 안에 다시 뜨지 않으면 실패로 확정돼요. 부팅 시간이 대기 시간 언저리인 앱은 배포마다 성공과 실패가 갈리니, 대기 시간을 넉넉히 잡으세요.

일단 이전 버전으로 되돌리고 싶어요

증상 — 원인을 찾는 것보다 먼저 서비스를 정상으로 돌려놔야 해요.

원인 — 문제는 최신 배포에 있어요. 잘 되던 이전 배포로 되돌리면 서비스부터 살릴 수 있어요.

해결 — 상황에 맞는 명령을 골라 실행하세요.

axhub deploy rollback --app <app> --from-deployment <deployment-id> --execute
axhub deploy cancel <deployment-id> --app <app> --execute
axhub apps suspend --app <app> --execute

deploy rollback — 지정한 예전 배포로 되돌려요(롤백).
deploy cancel — 진행 중인 배포를 중간에 멈춰요.
apps suspend — 앱을 잠시 내려요.

내렸던 앱을 다시 켤 때는 axhub apps resume을 쓰세요. 이때 마지막으로 성공한 프로덕션 배포를 백엔드가 알아서 다시 배포해요. 그 버전이 아니라 다른 커밋을 올리고 싶을 때만 axhub deploy create를 따로 실행하면 돼요.

접속이 안 돼요

증상 — 앱은 떠 있는데 나 또는 다른 사람이 들어갈 수 없거나, 스토어에 안 보여요.

원인 — 대개 공개 범위와 심사 문제예요. 새 앱은 나만 보이는 상태로 시작하고, 공개 범위를 넓히는 변경은 그때마다 심사를 거쳐야 반영돼요.

해결 — 아래 표에서 증상을 찾아 확인하세요.

증상	확인할 것
다른 사람이 못 들어와요	공개 범위가 나만보기면 본인만 가능해요. 일부공개면 그 사람을 초대했는지, 내부공개면 같은 회사(테넌트) 구성원인지 확인 (공개 · 접근 관리)
스토어에 안 보여요	내부공개 또는 외부공개 + 심사 승인이어야 스토어에 노출돼요
외부(회사 밖) 사람이 못 써요	공개 범위가 외부공개가 아니면 같은 회사 안에서만 접근할 수 있어요. 외부에 열려면 외부공개 심사를 받아요
공개 범위를 넓혔는데 반영이 안 돼요	넓히는 변경은 심사 승인이 나야 적용돼요 — 승인되는 순간 자동 전환되고, 좁히는 변경만 즉시 반영돼요 (공개 범위 넓히기)
들어오긴 하는데 로그인 사용자 정보가 비어요	서버에서 `X-AxHub-*` 헤더를 읽는지, email/name을 base64 디코드했는지 확인 (SSO 사용자 정보 읽기)

프리뷰가 안 열려요 · 만료됐다고 나와요

증상 — 프리뷰 화면이 열리지 않거나, 만료됐다는 안내가 나와요.

원인 — 프리뷰는 정식 공개 전에 앱이 잘 도는지 미리 확인하는 화면이라, 앱 자체가 정상으로 떠 있어야 열려요. 최신 배포가 실패했거나 아직 진행 중이거나, 앱을 일시 중지해 둔 상태면 프리뷰도 열리지 않아요. 만료 안내가 나올 때도 확인 순서는 같아요.

해결 — 앱 상태부터 차례로 확인하세요.

진행 중인 배포가 걸려 있으면

배포가 오래 멈춰 있으면 중간에 멈추고 다시 시도할 수 있어요.

axhub deploy cancel <deployment-id> --app <app> --execute

앱을 내려 둔 상태라면

axhub apps resume --app <app> --execute

apps resume은 마지막으로 성공한 프로덕션 배포를 자동으로 다시 배포해요. 앱이 다시 뜨면 프리뷰도 열려요.

Newt에서 앱을 만들다 막혔어요

증상 — Newt 채팅으로 앱을 만들거나 고치는데, 앱 작업 메시지에 오류 코드와 함께 멈췄다고 나와요.

원인 — 메시지의 오류 코드 · 단계 · 원인에 무엇이 막혔는지 나와요. 코드 보관 · Git 저장 · 미리보기 · 운영 배포는 각각 따로 표시돼서, 앞 단계에서 끝난 일은 그대로 남아 있어요.

해결 — 같은 일을 처음부터 다시 시키지 말고, 먼저 같은 작업의 상태를 물어봐요. 그다음 Newt 앱 개발 오류에서 코드에 맞는 할 일을 따라가요. 미리보기 링크에서 로그인 화면이 반복되면 브라우저 로그인이 반복돼요를 봐요.

방금 업무요청함 작업 상태 다시 확인해줘

그래도 안 되면

증상 — 위 어디에도 해당하지 않거나, 다 해 봤는데 그대로예요.

원인 — 화면과 로그만으로는 안 보이는 문제일 수 있어요. 이럴 땐 진단 정보를 모아서 문의하는 게 가장 빨라요.

해결 — CLI로 진단 번들을 모으고 문의를 보내요.

axhub support diagnose
axhub feedback --bug

axhub support diagnose — 지원 티켓용 진단 번들을 수집해요. 민감정보는 가려져요(마스킹).
axhub feedback — 제품 피드백 · 버그를 보내요 (--bug · --bug-critical · --suggest).

문의하기 전에, 에러 로그를 그대로 Claude Code나 Codex에 붙여넣어 보는 것도 잊지 마세요 — 대부분의 배포 실패는 여기서 풀려요.

배포 관리

배포 상태 · 로그 · 롤백의 자세한 절차

공개 · 접근 관리

공개 범위 · 심사 · 초대