These failures happen after the build worked, while HCode starts your app and checks that it answers. Each section starts with the message HCode shows, so you can search for yours.
Open the failed deployment on the Deployments tab. "What went wrong" has HCode's diagnosis, and a "Last output" box quotes the last line your app printed when there was one. The full output is in the runtime logs.
Nothing answers on the app's port
- "Your app's web address didn't respond. Most often the app isn't listening on the expected port."
- "The edge reached your app's web address but could not connect to your app (HTTP 502)." followed by "Nothing is accepting connections on port 3000." with your port number.
- "Your app looks like it is running a development server that only listens on localhost, so the edge can't reach it."
Your app has to listen on all interfaces, 0.0.0.0, on the port HCode gives it in PORT. A server bound to 127.0.0.1 or localhost can't be reached from outside its container. For example:
app.listen(process.env.PORT, '0.0.0.0');
gunicorn app:app --bind 0.0.0.0:$PORT
If the message adds "Note: your start command looks like it listens on port 8000, but the project is configured for port 3000.", the start command and the Runtime port setting disagree. Either change the command to use $PORT, or set Runtime port to the port the app uses (see Project settings).
A development server (npm run dev, vite, flask run) often binds to localhost only. Use a start command that serves the production build, or for a static site leave the start command empty and set the output directory. See Static sites.
The app answers with server errors
"Your app started but is returning server errors (HTTP 500). Check the app logs: it is reachable but crashing on requests."
The app is running, but requests to its root fail. Look in the runtime logs for the exception. A missing environment variable or a database the app can't reach are the usual causes. For Laravel apps, HCode recognises the common cases and says so, for example "Laravel needs an APP_KEY." or "Laravel can't reach its database.", with the variables to set.
The app blocks its own address
- "Your app is running but rejects every request for its web address (HTTP 400, Django's "Bad Request (400)" page)."
- "Your app is running but refuses requests for its web address (HTTP 403): it is blocking the hostname, which development servers and frameworks in development mode do."
- "Your app is running but answers with its framework's error page" followed by the status code.
HCode treats these as failures even though the app answered, because every visitor would get the same error page. Fix it for your framework, then deploy again:
| Framework | Fix |
|---|---|
| Django | Add the generated address and any custom domains to ALLOWED_HOSTS. |
| Rails | Set RAILS_ENV=production, or add the hostnames to config.hosts. |
| Vite | Serve the built app instead of the dev server, or set server.allowedHosts. |
The start command isn't in the image
- "Your app did not start: the container exited with code 127, which means the command it was told to run was not found in the image."
- "Your app did not start because the image it was built into has no "node" program, and that is what its start command runs." with the program's name.
- "Your app did not start because it tried to run a command that is not available in the image."
The start command, or the CMD or entrypoint of a Dockerfile, names a program the built image doesn't have. The most common case is a static site with a start command such as node index.js: a static build has no node. Clear Start command (optional) under Settings, or change it to a program your image installs, and deploy again.
A background worker exits
"Your background worker exited instead of staying running." or "Your background worker exited with code 1 instead of staying running."
A worker has no web address, so HCode only checks that its process keeps running. A worker whose start command finishes and exits fails the deploy. Make the start command run a long-lived process, and check the runtime logs for a crash on startup. See Web apps and workers.
The app crashes after starting
"Your app started, then stopped with an error. Its runtime logs show what it printed before it stopped."
If it keeps happening after the deploy, the project page also shows "This app is failing to start and may be crash-looping." The runtime logs show the error your app printed before each stop. Fix the cause, often a missing environment variable, then restart or deploy again.
The health check path fails
If you set Health check path (optional), the path must answer with a status below 400 when checked from inside the container. The app gets 60 seconds to start before failed checks count, and the image must contain wget, curl, node or python3 to run the check. See Web apps and workers. If your app has no such endpoint, leave the field empty.
Messages that aren't about your app
- "Your app's web address is reachable but its HTTPS certificate is not valid for that name, so the request was rejected before reaching your app."
- "Your app's web address could not be looked up in DNS, so nothing was reached."
On the generated address these point at HCode's edge, not your code. Deploy again after a few minutes, and email [email protected] if the message comes back. For a failure marked "On our side", see Failed deploys.
For static sites (a missing index.html, assets that return 404, source HTML served instead of the build), see Static sites.