Deploy / preview troubleshooting

Narrow failures using current deploy status, logs, doctor, and axhub.yaml contracts

First checks

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

Read status failure reason, latest logs, and doctor auth/endpoint/server-version output together.

Common causes

Symptom	Check
Dockerfile not found	root `Dockerfile`, Compose file, or `axhub.yaml` pinned start/manifest
compose file not found	`build.deploy_method: compose` and `build.compose_file` path
manifest parse/validation	under 8 KiB, `runtime.port` 1–65535, `ci.timeout` 1–600, max 10 `ci.commands`
required env missing	`axhub.yaml env.required` vs `axhub env list --app <app>` stage
GitHub repo/branch not found	`axhub apps git status --app <app>`, GitHub App installation/repo access
App loads but identity missing	Read `X-AxHub-*` server-side and base64-decode email/name

Rollback/recover

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

After apps resume, run deploy create again; resume does not auto-redeploy.