Fix a broken deploy
The link doesn't load, or the build failed. Symptom, cause and fix for the failures that actually happen.
Start here
read the logs for that app and tell me what went wrong
Your agent can read your app's build and runtime output and will usually name the cause and the fix in one go. The thing that wrote your app is also the thing that debugs it — you do not have to understand the error yourself.
If you want to follow along, the rest of this page is what it's looking for.
Symptom → cause → fix
| What you see | Almost always | Fix |
|---|---|---|
Status goes to running, then the page 502s or won't load | The app started and immediately exited — usually the entrypoint isn't where the runtime looks | Check the runtime's convention |
| Python: build succeeds, container crash-loops | The file isn't app.py, or the object in it isn't called app | Rename to app.py exposing app, or wrap it so that name resolves |
| Python: "gunicorn: not found" | gunicorn missing from requirements.txt | Add it — it's what serves the app |
| Node: "Missing script: start" | No start script in package.json | Add "start": "node server.js" |
| Node: build fails on install | Lockfile out of sync with package.json | Ship both, or neither |
| Build fails on a missing module you do have | You shipped node_modules / vendor instead of the manifest | Send your source; dependencies are installed for you |
| The app ignores a setting you asked for | You passed a field that doesn't exist — unknown fields are silently ignored | There is no start command and no port setting. Use the runtime's convention |
Static site: / works, other paths 404 | A single-page app doing client-side routing | Hash routing, pre-render the routes, or serve it from a Node app |
| PHP: blank page | A PHP error with display off | Read the logs |
| Everything looks fine but the URL says the site can't be found | A custom domain whose DNS hasn't propagated | See Use your own domain |
| Visitors see a sign-in screen you didn't expect | The app is invite-only | Make it public again |
| The result says "simulated" | Hosting isn't configured on this server — nothing was built or served | Treat it as a failed deploy, not a success |
The three that account for most of it
The Python entrypoint. agenthost imports the name app from app.py. Not main.py, not
application. This is a fixed convention, not a parameter — it's the single most common failure on
the platform.
A Node app with no start script. npm start needs one. Without it there's nothing to run.
Trusting the first status. A deploy call returns when the build is queued. Poll until the status settles, then confirm with a real request. Two reads, and you avoid most false "it worked".
When the build itself fails
Build failures are in the logs, in the same place as runtime errors. Common ones:
- A dependency that needs system packages we don't install. Bring your own Dockerfile if you need them.
- A
buildscript that fails. For Node,npm run buildruns automatically when present — if it fails, the deploy fails. - A package version that doesn't exist for the runtime version you pinned. See Choosing a version.
Still stuck
Give your agent everything at once:
here's the app id — fetch its status, read 300 lines of logs, fetch the URL, and tell me what you'd change
That's three tool calls it can make on its own, and between them they almost always contain the answer.