Troubleshooting
Narrow down deploy failures, access problems, and preview errors by symptom and fix them.
When something's stuck, narrowing it down by symptom is fastest. Pick the heading closest to what you're seeing and follow it in symptom → cause → fix order.
Remember one thing: pasting error logs into Claude Code as-is, not summarized, is the fastest way to find the cause.
Deploys aren't working
App creation failed
Symptom — while creating an app (bootstrap), a failure message and a Retry button appear on screen.
Cause — it's usually a repository name, GitHub App installation, or address-format problem, and the on-screen message says exactly what went wrong.
Fix — take the action matching the message, then retry.
| Message | Fix |
|---|---|
| A repository with this name already exists | Go back to the Git repository step and retry with a different repository name |
| GitHub App installation required | Complete installing the axhub GitHub App in the Git repository step |
| Slug / subdomain format error | Use only lowercase letters, digits, and hyphens |
| App creation failed | It may be temporary — try again in a moment |
A deploy shows as failed
Symptom — you pushed code to GitHub, but the deploy tab shows Failed.
Cause — usually the build/start command, port, environment variables, Dockerfile, or axhub.yaml (manifest) doesn't match the actual code.
Fix — narrow the cause with three commands, find your symptom in the common-causes table, fix it, and push again.
Narrow it down with three commands
Put the ID of the deploy you're checking in <deployment-id> and the app name in <app>.
axhub deploy status <deployment-id> --app <app> --json
axhub deploy logs <deployment-id> --app <app> --limit 200
axhub deploy doctor --app <app>The three tell you different things. Looking at just one makes it easy to miss the cause, so use them together.
status— tells you why this deploy stopped (failure reason).logs— the errors that actually occurred while running. Start from the last error line.doctor— checks your environment, not the deploy itself. It verifies your login state, endpoint (the address you're connecting to), and server version.
Find it in the common-causes table
Open the deploy logs, see how far the build got before it stopped, find the closest symptom in the left column below, and check the right column.
| Symptom | What to check |
|---|---|
| Dockerfile not found | The root must contain one of Dockerfile, a Compose file, or axhub.yaml |
| Compose file not found | build.deploy_method: compose and the build.compose_file path |
| Build/run command unknown | Write build and start commands in axhub.yaml (axhub.yaml reference) |
| Manifest format / validation error | 8 KiB or less, runtime.port 1–65535, runtime.entry_service (compose only), ci.timeout 1–600, ci.commands up to 10 |
| Missing environment variable error | Check that env.required in axhub.yaml matches the Stage in axhub env list --app <app> (Set environment variables) |
| Changed an env var but nothing changed | Environment variable changes take effect only after a redeploy |
| Repository / branch not found | Check the GitHub connection with axhub apps git status --app <app>, and verify GitHub App installation, repository permissions, and the branch (main) |
Entry service not found (build.entry_service_not_found) | Check that the runtime.entry_service name in axhub.yaml matches a service in the compose file — the failure message lists the actual services |
Entry service has no port (build.entry_service_has_no_port) | Add a ports: or expose: declaration to that service (Compose entry service) |
Fix and push again
After fixing, push the commit to GitHub again and confirm a new deploy runs. The detailed procedures for deploy status values, reading logs, and rolling back are in Managing deploys.
I just want to roll back to the previous version
Symptom — you need to get the service back to normal before finding the cause.
Cause — the problem is in the latest deploy. Rolling back to a previous deploy that worked gets the service back first.
Fix — pick the command that fits your situation and run it.
axhub deploy rollback --app <app> --from-deployment <deployment-id> --execute
axhub deploy cancel <deployment-id> --app <app> --execute
axhub apps suspend --app <app> --executedeploy rollback— reverts to the earlier deploy you specify (rollback).deploy cancel— stops a deploy that's in progress.apps suspend— takes the app down temporarily.
To bring a suspended app back up, use axhub apps resume. When you do, the backend automatically redeploys the last successful production deploy. Only run axhub deploy create separately if you want to ship a different commit instead of that version.
I can't access the app
Symptom — the app is up, but you or someone else can't get in, or it doesn't show in the store.
Cause — it's usually a visibility or review issue. New apps start visible only to you, and any change that widens visibility takes effect only after passing review each time.
Fix — find your symptom in the table below and check.
| Symptom | What to check |
|---|---|
| Other people can't get in | If visibility is only me, only you can access. For invite-only, check that you invited that person; for everyone, check they belong to the same company (tenant) (Visibility and access) |
| It doesn't show in the store | The app must be Internal or External visibility + review approved to appear in the store |
| People outside the company can't use it | Unless visibility is internet, only people inside the company can access it. To open it externally, go through the internet visibility review |
| I widened visibility but nothing changed | Widening changes apply only after review approval — the switch happens automatically the moment it's approved; only narrowing changes apply immediately (Widening visibility) |
| People get in, but signed-in user info is empty | Check that the server reads the X-AxHub-* headers and that you base64-decoded email/name (Read the SSO user info) |
The preview won't open, or says it expired
Symptom — the preview screen doesn't open, or shows an expired notice.
Cause — the preview is a screen for checking that the app runs well before publishing, so the app itself must be up and healthy for it to open. If the latest deploy failed, is still in progress, or the app is suspended, the preview won't open either. When you see an expired notice, the checks are the same.
Fix — check the app's state in order.
Check the latest deploy's status
axhub deploy status <deployment-id> --app <app> --jsonIf it shows failed, narrow down and fix the cause following A deploy shows as failed above.
If a deploy is stuck in progress
If a deploy has been stalled for a long time, you can stop it midway and try again.
axhub deploy cancel <deployment-id> --app <app> --executeIf the app is suspended
axhub apps resume --app <app> --executeapps resume automatically redeploys the last successful production deploy. Once the app is back up, the preview opens too.
Still stuck?
Symptom — none of the above applies, or you tried everything and it's still the same.
Cause — it may be a problem you can't see from the screens and logs alone. In that case, the fastest path is gathering diagnostic info and contacting support.
Fix — collect a diagnostic bundle with the CLI and send an inquiry.
axhub support diagnose
axhub feedback --bugaxhub support diagnose— collects a diagnostic bundle for a support ticket. Sensitive info is masked.axhub feedback— sends product feedback and bugs (--bug,--bug-critical,--suggest).
Before contacting support, don't forget to paste your error logs into Claude Code as-is — most deploy failures get solved right there.