How to Fix 502 Bad Gateway Nginx (A Step by Step Guide)

Introduction

If you’ve deployed a backend app behind Nginx and suddenly see 502 Bad Gateway in your browser, don’t panic — this is one of the most common deployment problems.

When I first faced this error, I thought Nginx was broken. I restarted it multiple times, but the real problem was my backend server. A 502 error happens when Nginx tries to contact your backend (FastAPI, Django, Node.js, etc.), but the backend either doesn’t respond or Nginx cannot connect to it.

In this guide, I’ll show you how to identify the cause and fix it, step by step, with real commands and examples.

What 502 Bad Gateway Means?

A 502 Bad Gateway is an HTTP status code returned by Nginx. Think of Nginx as a receptionist: it asks your backend “Can I get a page?” If the backend doesn’t reply, the receptionist sends back 502 Bad Gateway.

Common Causes

There are certain reasons you are seeing 502 Bad Gateway, here are the most common causes:

1. Nginx acts as a gateway or reverse proxy
2. The backend server (your app) does not respond properly
3. Nginx receives an invalid or no response

Step 1: Check if Your Backend Server is Running

The first thing I check is whether my backend is actually running. I’ve wasted hours thinking Nginx was broken, only to find my server wasn’t running at all.

For Python apps (FastAPI, Django, Flask):

ps aux | grep python

For Node.js apps:

ps aux | grep node

Look for your server script, like main:app for FastAPI or server.js for Node.

If you don’t see your server running: start it immediately.

How to Start the Server?

Django:

python manage.py runserver 0.0.0.0:8000

FastAPI:

uvicorn main:app --host 0.0.0.0 --port 8000

Node.js:

node server.js

Tip: Forgetting --host 0.0.0.0 is a very common mistake. Nginx cannot connect if you only bind to 127.0.0.1 or localhost.

Step 2: If Backend is Running — Check Nginx Configuration

If your server appears in the logs, the problem is usually Nginx not reaching the backend.

Check your Nginx site configuration:

server {
    listen 80;
    server_name yourdomain.com;
 
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Check and reload Nginx:

sudo nginx -t 
 
sudo systemctl reload nginx

I once spent 30 minutes debugging a 502 because proxy_pass was pointing to the wrong port. Double-check the port your backend is running on.

Step 3: Optional — Check Logs for Clues If the issue still persists, the only best method to debug the issue is to check the logs.

Check Nginx Error Log:

/var/log/nginx/error.log

Check Backend logs:

• PM2 logs for Node.js
• Terminal logs for Python apps

Pro tip: Real errors usually appear here, not in your browser.

Summary

502 Bad Gateway errors happen because Nginx cannot talk to your backend.

Step 1: Check if your backend server is running

Step 2: Check Nginx config (proxy_pass, port, host)

Step 3: Check logs if needed Once you fix the connection, the 502 error disappears.

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:8000

If 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.

If you really found this blog helpful, please share it with others and subscribe to our newsletter for more valuable blogs. Thank you for reading!