문제 해결

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

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

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

배포가 안 돼요

앱을 만들다 실패했어요

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

원인 — 대부분 저장소 이름 · 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` 중 하나가 있어야 해요
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 전용), `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 진입 서비스)

고치고 다시 올리기

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

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

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

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

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

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은 마지막으로 성공한 프로덕션 배포를 자동으로 다시 배포해요. 앱이 다시 뜨면 프리뷰도 열려요.

그래도 안 되면

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

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

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

axhub support diagnose
axhub feedback --bug

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

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

배포 관리

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

공개 · 접근 관리

공개 범위 · 심사 · 초대