Why does your site show 502 Bad Gateway after a deploy?
Because the web server in front of your app could not get an answer from it: the app crashed on start, is listening on the wrong port, is bound to localhost only, or ran out of memory. The build can succeed and the site still return 502, since the build only proves the code compiled, not that the server started. The start-up lines of the runtime log name the cause in almost every case, and on Hostwares the agent reads them and proposes the fix.
Step by step
- 1
Read the runtime log, not the build log
Open the site's Logs tab and look at the first lines after the start command. Over MCP, diagnose_site reads the status, the recent logs and the last deploy and returns one verdict.
From an agent over MCP
diagnose_site → cause + suggested fix get_logs → the raw runtime lines - 2
Crash on start: a missing variable or module
An error such as a missing environment variable or module, followed by the process exiting, means the server never started. Add the variable on the Environment tab (list_env_vars shows what is set) or fix the dependency and redeploy.
- 3
Wrong port or localhost only
The log says the server is listening, but on another port or on 127.0.0.1. Listen on the PORT variable and on 0.0.0.0, or tell the platform which port the app uses.
Set the port over MCP
set_app_port → the port your app listens on - 4
Out of memory
The process is killed shortly after start, often during a large build or the first requests. Move to a pack with more memory, or reduce what the app loads at start.
- 5
Roll back if users are waiting
If the previous version worked, return to it first and debug after. rollback_site does it over MCP; the Deployments tab has the same action.
What it costs
- Reading logs and rolling back cost nothing beyond the pack, from $1/mo.
- HW, the AI agent, bills its own usage in AI credits; diagnosing with the dashboard or MCP tools does not need it.
App
$1/mo
Starter Frontend pack, 1 vCPU / 1 GB RAM / 10 GB
Database, users and files
$5/mo
Smallest dedicated Supabase pack; several projects fit on one
Questions
The build passed. Why is the site still down?+
The build only compiles the code. A 502 comes later, when the server process fails to start or does not answer on the expected port.
Is a 502 a problem with my domain or DNS?+
No. A 502 means the request reached the server in front of your app. DNS problems show as the site not resolving at all.
What is the difference between 502 and 504?+
502 means the app gave no valid answer. 504 means it took too long. A 504 points at a slow query or an external call rather than a crash.
Can an AI find the cause for me?+
Yes. HW in the dashboard, or Claude Code and Cursor over MCP, can read the logs, name the cause and apply the fix once you approve it.
It works on my computer. Why not in production?+
Usually a variable that exists only in your local .env file, or a server that listens on localhost. Both show in the first lines of the runtime log.
How do I stop it happening again?+
Listen on PORT and 0.0.0.0, fail fast with a clear message when a variable is missing, and check one endpoint after each deploy.