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 or Codex 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 | Put a Dockerfile or a Compose file at the root. axhub.yaml alone may not be enough (unless it sets static, a dockerfile, or pinned+start, detection continues). Conversely, Node · Python · Go · Ruby · Java can deploy with none of the three via auto-detection (How the build is decided) |
| 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), runtime.healthcheck values need a unit like 90s, 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) |
Build finished but the app never came up (healthcheck.startup_budget_exceeded · healthcheck.container_crash) | The app is restarted if it does not answer the health check within 60 seconds. Move migrations and seeding out of the start command, and if boot takes longer, raise runtime.healthcheck.start_period in axhub.yaml (Health check wait time). Per-code fixes are in Health check failure codes below |
The log shows spawn … ENOENT or not found, but the file is clearly there | A prebuilt binary (workerd, sharp, the Prisma engine, and so on) cannot run on the Alpine image (musl). Change FROM node:22-alpine to FROM node:22-slim in your Dockerfile. A Dockerfile generated by axhub import is a file in your repository, so you can edit it |
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.
Health check failure codes
Symptom — the build finished, but the deploy failed and the failure reason code starts with healthcheck..
Cause — the deploy stalled while the new container was coming up. The code tells you where. The failure reason is shown in the Deploy tab of the app console, or by axhub deploy status <deployment-id> --app <app> --json.
Fix — apply the action for the code and push again.
| Code | Meaning | What to do |
|---|---|---|
healthcheck.startup_budget_exceeded | No first response within the health check wait time (the message shows it in seconds), so the platform restarted the container. The app itself was alive | Raise runtime.healthcheck.start_period, or shorten boot by moving migrations and seeding out of the start command (Health check wait time) |
healthcheck.container_crash | The container exited on its own or exceeded its memory | Check the last error line in the app log and the resource settings. If that line is spawn … ENOENT, the base image does not match the app's dependencies (see the causes table above). If you expected a wait-time overrun but see this code, reproduce with a new deploy — on an old deployment the evidence used to tell them apart may already be gone |
healthcheck.image_pull_failed | The container image could not be pulled | Image name and registry permissions |
healthcheck.container_config_error | Environment variables, secrets, or container configuration are wrong | Check names and Stage with axhub env list --app <app> |
healthcheck.rollout_timeout | The rollout did not stabilize in time | Check the app log and the health_path response, then redeploy |
healthcheck.capacity_wait_timeout | The cluster had no room. Not an app problem | Redeploy a little later |
healthcheck.deployment_cancelled | The deploy was cancelled midway | Start a new deploy when ready |
healthcheck.targets_unresolved · healthcheck.diagnosis_unavailable | The platform could not fully read the deploy state | Start a new deploy |
A restarted container that does not come up again within 60 seconds is marked failed. Apps whose boot time sits right at the wait time will pass or fail from one deploy to the next, so leave headroom.
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.
Stuck building an app in Newt
Symptom — you're building or changing an app by chatting in Newt, and an app-task message says it stopped with an error code.
Cause — the message's error code, stage, and cause say what got stuck. Code capture, Git save, preview, and production deploy are reported separately, so whatever finished before the failed stage stays done.
Fix — don't ask for the same thing from scratch; first ask for the status of the same task. Then follow the action for that code in Newt app development errors. If the preview link keeps showing a login screen, see The browser keeps asking me to sign in.
Check the status of the Request Inbox task againStill 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 or Codex as-is — most deploy failures get solved right there.