Nginx 502 Bad Gateway: how to find the real error on your server
Published on 2026-10-26 by frfrand
Guide to diagnosing 502 between Nginx, Gunicorn, and FastAPI
The browser shows 502 and the first thing someone proposes is changing the DNS. But if Nginx is responding, you probably already reached the proxy. The error is usually between Nginx and the application it is trying to connect to.
Let's turn it into a procedure you can use on a real VPS. The goal is to understand why it works, how to test it, and what problem appears if one part is misconfigured.
What Nginx 502 Bad Gateway means and when you need it
A 502 indicates that the proxy received an invalid response or failed to communicate correctly with the upstream, among other causes. It can happen because Gunicorn did not start, is listening on another port, closed due to lack of RAM, or the Unix socket has incorrect permissions.
Before changing anything in production, note the current status: IP, domain, port, affected service, and time of the last deploy. An isolated change is easy to verify; five simultaneous changes make it harder to reconstruct what happened.
Example configuration or commands
sudo nginx -t
sudo tail -n 80 /var/log/nginx/error.log
sudo systemctl status miapp
sudo journalctl -u miapp -n 100 --no-pager
sudo ss -ltnp
curl -i http://127.0.0.1:8000/healthDomains, IP, paths, and names are illustrative. Do not copy an entire configuration over the current one without comparing first. In examples that include ports or firewall, make sure to keep administrative access.
How I would do it step by step
- Preparation. Check if the 502 is returned by Nginx and if the domain points to the expected server.
- Step 2. Check the Nginx error log to find the exact upstream address.
- Step 3. Review the systemd unit of Gunicorn/Uvicorn and the first startup error.
- Step 4. Test the backend local port directly to isolate the proxy.
- Verification. Fix the specific problem and verify a real operation over HTTPS.
When finished, check the real operation from another connection. For example, for an API it is not enough to open the browser: run a read request, a write to a test database, and check the process logs.
Example of a real project
After a Django deploy, Gunicorn fails because the virtual environment no longer exists at the indicated path. Nginx works fine, but it has no one to talk to. The systemd logs show the cause in seconds.
The lesson is simple: an infrastructure configuration does not live isolated from the application. The frontend, the server, the database, and the workers connect, so measuring where the failure starts is more useful than restarting everything.
The error I would avoid
Do not restart PostgreSQL, Nginx, and the entire machine simultaneously: you lose evidence. Also, do not attribute a 502 to the certificate without verifying that it occurred after establishing TLS.
When working with client servers, keep a backup or rollback procedure before changes that affect data, network, or certificates. And if you don't know what permissions an operation requires, avoid running it as root just to stop errors from showing up.
How does it relate to ArduMaker?
With ArduMaker you can correlate service logs and the last deployment on the VPS. If a build completed but the process doesn't start, the error is in the startup and not necessarily in Git.
In a typical case you can create a VPS for the application, deploy from Git, associate an HTTPS domain, and manage the backend and necessary databases. The tools help centralize operations, but you need to understand which port and process fulfills each function.
Questions that arise when you try it
How do I know if the failure is DNS or the service? Check resolution first, then connection to the port, and finally the application response. That order avoids confusing different problems.
Can I expose a database to make it easier to maintain? Better design private access or authenticated tunnels when possible. Exposing a port does not replace engine permissions or the firewall.
What should I document? The expected configuration, how it is verified, and how to return to the previous state. That document helps you more than a list of commands without context.
References
In summary: a good network or server configuration is one that you can explain, verify, and recover when something fails.