When something breaks
502 Bad Gateway after deploying a site: what it means and how to fix
In short
A 502 Bad Gateway error means the proxy server that receives visitors could not get a response from your application. Most often the app crashed on startup, listens on localhost or on the wrong port, has not finished starting yet, or was stopped for running out of memory. The cause is almost always visible in the app logs: an error at startup, a startup line showing 127.0.0.1, or the word Killed. The page code itself is usually not to blame, because the request never reached it.
- A 502 Bad Gateway error means the proxy server in front of an app did not get a proper response from it.
- An app that listens on 127.0.0.1 or localhost is unreachable for the proxy and shows up from outside as a 502 error.
- If an app listens on a port other than the one in the PORT environment variable, the proxy knocks on the wrong door and returns 502.
- The word Killed or exit code 137 in the logs usually means the app was stopped because it ran out of memory.
- A 504 Gateway Timeout, unlike 502, means the app did not crash but failed to answer in time.
The site is deployed, you have a link, and instead of a page you get 502 Bad Gateway. It sounds like the server broke, but usually the server is fine. In front of your app there is always a middleman, a proxy server: it receives visitors, handles HTTPS and passes requests on to your app. A 502 is its way of saying I passed the request along, but the app did not answer, or answered with something I could not understand.
So the place to look is not the hosting settings but the app itself: is it running at all, is it listening in the right place, and does it have enough resources. The answer is almost always in the logs. Below are the causes in order of frequency and how to check each one.
| What you see | Likely cause | What to do |
|---|---|---|
| Always 502, logs show an error and restarts in a loop | The app crashes on startup | Find the first error in the logs and fix it |
| Always 502, logs say Running on 127.0.0.1 | The app listens on localhost | Bind to 0.0.0.0 |
| Always 502, logs show port 5000, 8000 or 3000 | The port is hardcoded | Read the port from the PORT variable |
| 502 for the first minutes after deploying, then it opens | Slow startup: loading a model or data | Wait, or speed up startup by loading heavy things in the background |
| 502 now and then, logs show Killed or code 137 | Not enough memory | Reduce memory use or pick a plan with more memory |
| 502 only on one page or action | That request crashes the app | Open the page and immediately check the error in the logs |
Open the logs and find the first error#
Start with the app logs, not the page code: a 502 is almost always explained there. If the app crashes on startup, the logs show an error, then a restart and the same error again, so look at the very first one, since the rest just repeat it. Typical culprits are a missing library, the wrong file name to start, or a token or database password that was never set. Fix that error and deploy the project again.
Check the address: 0.0.0.0, not localhost#
If the app starts without errors, find the log line where it says which address it listens on. If it says 127.0.0.1 or localhost, the app accepts connections only from inside its own machine, and the proxy cannot reach it. Bind to 0.0.0.0: in Flask that is the host argument, in uvicorn the --host flag, in gunicorn the --bind flag. This is the most common cause of a 502 for a site that works perfectly on your computer.
Check the port: it must come from the PORT variable#
The proxy forwards requests to the port the host passes to your app in the PORT environment variable. If 5000, 8000 or 3000 is hardcoded, the app runs, but on another port, and the proxy answers 502. Read the port from PORT and keep a number only as a fallback for running locally. On Netrun the platform sets PORT itself, and for a project with its own Dockerfile the port is taken from the first EXPOSE line.
Give the app time to start#
If the 502 appears only in the first seconds or minutes after deploying and then the site opens, the app is simply slow to start. Usually it is loading a neural network model, a large data file or warming up a cache right at startup. Until the app starts listening on its port, the proxy answers 502. Wait it out, and if startup is too slow, move the heavy loading to the background so the site answers right away while the model finishes loading.
Check whether there is enough memory#
If the site sometimes opens and sometimes returns 502, and the logs contain the word Killed or exit code 137, the app was stopped for running out of memory and is restarting. Memory is most often eaten by neural network models, reading large files in one go, big pandas tables, and several server worker processes where one would do. Reduce the number of workers, read files in chunks, or choose a plan with more memory. There is a separate guide on the Killed error with more detail.
If 502 hits one page only, reproduce it and watch the logs#
Sometimes the home page opens and the 502 shows up only on a specific page or after pressing a button. That means this particular request crashes the app: an unhandled error, an operation that is too heavy, or running out of memory on a large file. Open the logs, repeat the action and look at what appears at the end: there will be an error message with a line number. If the page does not crash but just thinks for too long, you usually get 504 Gateway Timeout instead of 502, and the slow work should be moved to the background.
A 502 Bad Gateway after deploying is almost always about the app, not the host: it did not start, it listens on the wrong address or port, it is still loading, or it runs out of memory. Start with the logs, then check for 0.0.0.0 and the port from PORT, and that covers most cases. On Netrun the project status and live logs are in your dashboard, a crashed app is restarted automatically, and you get a notification if the project stays down for a long time. For a site that must open instantly at any hour there is the Pro plan: on the free plan a site sleeps when nobody visits, and the first visit after sleep takes a few seconds. Try Netrun.
Common questions
What does 502 Bad Gateway mean in plain words?
In front of your site there is a middleman that receives visitors and passes requests to your app. A 502 means the middleman passed the request on and the app did not answer: it is not running, it crashed, or it listens in the wrong place. The app needs fixing, not the browser or the visitor connection.
Why does my site work locally but return 502 after deploying?
Most often because the app listens on localhost or on a hardcoded port. On your computer the browser and the app share one machine, so everything works, while on the server the proxy connects from outside and to a different port. Bind to 0.0.0.0 and read the port from the PORT variable.
What is the difference between 502 and 504?
A 502 means the app did not answer at all or answered incorrectly, usually because it is not running or crashed. A 504 Gateway Timeout means the app is running but did not answer within the waiting time. Look for the first in the startup logs and for the second in slow requests.
Can a 502 go away on its own?
Yes, if the app was just slow to start or was restarting after a failure: within seconds or minutes the site opens. But if the 502 stays or keeps coming back, it will not go away by itself, and the logs will show a cause that needs fixing.
What if the logs show no errors but the site returns 502?
Look at the line where the app reports that it started, since it shows the address and port. No errors together with a 502 almost always means the app is running but listening on localhost or the wrong port. Change the address to 0.0.0.0 and take the port from the PORT variable.
My project will not open — what should I do?
Open the project page and check its status and logs. If you cannot figure it out, email us.
What happens if my app crashes?
We watch over projects and restart them if they fail. The status and the logs appear in your account straight away, and we send a notification only if the app has not come back within an hour: short interruptions are not worth disturbing you over.
Where can I see the logs and status of my project?
The project page shows the status, the logs and the event history — together they show what is happening with the project right now. The log view also reaches further back: scroll up and earlier lines load on their own.