When a deploy fails
Narrow down app-build failures, deploy failures, and access issues by symptom.
When something's stuck, narrowing it down by symptom is fastest. And remember one thing — paste error logs into Claude Code exactly, without summarizing; that's the quickest way to find the cause.
The app build failed
If building the app (bootstrap) fails midway, the screen shows a message and a Retry button. Common cases:
| Message | Fix |
|---|---|
| A repo with that name already exists | Go back to the Git repo step and try a different repo name |
| GitHub App install required | Complete the axhub GitHub App install in the Git repo step |
| Invalid slug / subdomain format | Use lowercase letters, digits, hyphens only |
| App creation failed | May be temporary — try again in a moment |
A deploy failed
If you pushed code and the Deploy tab shows a failure, look at the deploy log first.
| Symptom | What to check |
|---|---|
| Dockerfile not found | The root needs a Dockerfile, a Compose file, or an axhub.yaml |
| Build/start command unknown | Set build/start in axhub.yaml (Develop the app) |
| Missing env var error | Check it's registered in environment variables with the right Stage |
| Changed an env var but nothing changed | Env changes take effect on the next deploy |
| Repo/branch not found | Check the GitHub connection and branch (main) |
Then fix → push to GitHub → new deployment, and try again.
I can't access the app
| Symptom | What to check |
|---|---|
| Others can't get in | If visibility is private, only you can. If invite-only, check you invited them (Access management) |
| It's not in the store | Only public + approved shows in the store (check the operating status is "Running") |
| People outside the company can't use it | That's by design. The app is reachable within your company only |
| They get in but the logged-in user is empty | Check you read the X-AxHub-* headers on the server (Develop the app) |