Introduction
If you have deployed your app behind the Nginx and got 502 Bad Gateway Nginx, you know how frustrating it feels staring at the blank screen. The good news is that this error always has a clear, flexible cause. In this guide you will learn exactly how to diagnose and fix it in simple steps.
Table of Contents
- Introduction
- What is a 502 Bad Gateway Error?
- Why Does Nginx Return a 502?
- How to Diagnose a 502 Bad Gateway Error
- How to Fix a 502 Bad Gateway Error
- FAQ – 502 Bad Gateway in Nginx
- Summary
What is a 502 Bad Gateway Error?
A 502 Bad Gateway is an HTTP status code. When your browser shows this error, it means the Nginx server acting as a gateway or proxy received an invalid response from another server behind it.
Let’s break it down in simple terms. When you visit a website, your request does not always go directly to one server. Often, it passes through a chain:
Your Browser → Nginx (reverse proxy) → Your App (FastAPI, Node.js, etc.)In this setup Nginx is the middleman. Its job is to receive your request and forward it to the actual application — like Node.js, Django, or FastAPI running on the same server. When Nginx can't get a valid response back from that application, it returns a 502 Bad Gateway Nginx to your browser.
This is different from a 500 Internal Server Error, which means the server itself crashed. A 502 specifically means the communication between two servers broke down.
Why Does Nginx Return a 502?
There are several common reasons this happens:
1. Your Backend App Is Not Running
This is the most common cause. If your Node.js, Django or FastAPI is not running, Nginx has nothing to forward requests to, so it returns 502. This can happen when:
- You forgot to start the app after deploying
- The app crashed due to a startup error (missing environment variable, syntax error, etc.)
- Your server rebooted and the app didn't auto-start
2. Wrong Port Configuration
Nginx needs to know which port your backend app is listening on. If there's a mismatch — for example, Nginx is configured to forward to port 8000, but your app is running on port 8001 — you'll get a 502.
Example of a correct Nginx config:
location / {
proxy_pass http://127.0.0.1:8000; # Must match your app's port
}3. The App is Starting Up (Temporary 502)
When you restart a server or redeploy your app, there's a brief window where the app isn't ready yet. During this time, Nginx will return a 502. This is usually temporary and resolves within seconds.
4. App Crashed Mid-Request
Your app might start fine, but crash under certain conditions — a bad database query, an unhandled exception, or a memory error. When this happens during an active request, Nginx gets no response and returns 502.
How to Diagnose a 502 Bad Gateway Error
When you see 502, don’t guess the cause. Always check the logs. Here is the step by step approach:
Step 1: Check If Your Backend Is Running
If you are running your app using systemd, check your app using the following command:
sudo systemctl status your-app-nameIf you don’t use systemd, check the running processes using:
ps aux | grep uvicorn # for FastAPI
ps aux | grep node # for Node.jsIf you are using PM2, check your application using:
pm2 listIf the service is inactive or dead, restart it to fix the issue.
Step 2: Read the Nginx Error Log
sudo tail -n 50 /var/log/nginx/error.logLook for the messages like:
- connect() failed (111: Connection refused) — means backend isn't running
- no live upstreams while connecting to upstream — means all backend servers are down
- upstream timed out — means backend is running but too slow to respond
Step 3: Test the Backend Directly
If your app is supposed to run on port 8000, test it without Nginx:
curl http://127.0.0.1:8000If this returns an error or times out, the issue is with your app — not Nginx. If it returns a valid response, the issue is in your Nginx configuration.
Step 4: Verify Your Nginx Config
sudo nginx -tThis checks your Nginx configuration for syntax errors. Also double-check the proxy_pass line points to the correct host and port.
How to Fix a 502 Bad Gateway Error
Once you've identified the cause, here are the fixes:
Fix 1: Start or Restart Your Backend App
If using systemd:
sudo systemctl start your-app-name
# or
sudo systemctl restart your-app-nameEnable auto-start on reboot:
sudo systemctl enable your-app-nameIf using PM2:
pm2 start your-app-name
#or
pm2 restart your-app-nameFix 2: Fix the Port Mismatch
Open your Nginx config (usually in /etc/nginx/sites-available/) and make sure proxy_pass points to the right port:
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://127.0.0.1:8000; # — Confirm this matches your app
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}Then Reload Nginx:
sudo nginx -t && sudo systemctl reload nginxFix 3: Increase Upstream Timeout (If App Is Slow)
If your backend takes longer than Nginx's default timeout, Nginx gives up and returns 502. You can increase the timeout:
location / {
proxy_pass http://127.0.0.1:8000;
proxy_read_timeout 120s;
proxy_connect_timeout 120s;
proxy_send_timeout 120s;
}FAQ – 502 Bad Gateway in Nginx
Can 502 Bad Gateway happen even if my backend is running?
Yes. Even when my FastAPI server was running, Nginx couldn’t reach it because I had the wrong port in proxy_pass. Always double-check your backend host and port.
Does 502 mean Nginx is broken?
No. Most of the time, Nginx is fine. The error usually comes from the backend not responding, or misconfiguration in Nginx.
How can I quickly test if the backend is reachable?
Use curl to test your backend:
curl http://127.0.0.1:8000If you get a valid response, Nginx should work too. If not, the backend is the problem.
Is 502 different from 504 Gateway Timeout?
Yes. 502 means the backend sent an invalid response or no response at all. 504 means the backend took too long to respond.
Can this happen for Node.js, Django, and other apps too?
Absolutely. I’ve seen this error with Node.js, Django, FastAPI, and even PHP. The root cause is always the same: Nginx can’t get a proper response from your backend.
Summary
A 502 Bad Gateway from Nginx almost always means your backend application is unreachable. The most common culprits are a crashed or stopped backend process, a misconfigured port in your Nginx config, or an app that's too slow to respond.
The fix is straightforward once you know where to look: check the Nginx error logs, verify your app is running, test the backend directly with curl, and confirm your proxy_pass configuration is correct.
If you really found this blog helpful, please share it with others and subscribe to our newsletter for more valuable blogs. Thank you for the reading!