502
Bad Gateway
5xx Server Error
What Does HTTP 502 Bad Gateway Mean?
HTTP 502 Bad Gateway means a server acting as a gateway or proxy received an invalid response from an upstream server. This is not a problem with your request or your connection — it is a communication failure between two servers.
In modern web architecture, requests often flow through multiple layers: CDN (Cloudflare, CloudFront) → Load Balancer (ALB, Nginx) → Application Server (Node.js, PHP-FPM, Gunicorn). A 502 means one of these intermediate layers could not get a valid response from the next layer in the chain.
The key distinction from other 5xx errors: 502 specifically involves two servers, where the front-facing server (gateway) blames the backend server for the problem.
Common Causes
- Backend application crashed: The Node.js, Python, PHP, or Java application server has crashed, been killed by OOM (Out of Memory), or is in the process of restarting. Nginx or the load balancer cannot connect to it at all.
- PHP-FPM not running or overloaded: Nginx proxies PHP requests to PHP-FPM. If the FPM process pool is exhausted (all workers busy) or the service is stopped, Nginx returns 502. Check with
systemctl status php-fpm. - Wrong proxy_pass address or port: Nginx is configured to forward to
localhost:3000but the app is listening on port8080. Or the socket file does not exist:proxy_pass unix:/tmp/app.sockbut the file is missing. - Backend returned invalid HTTP: The upstream server sent a response that is not valid HTTP — malformed headers, incomplete response, or binary data where HTTP was expected. This can happen with misconfigured backends or protocol mismatches.
- Upstream connection reset: The backend accepted the connection but then crashed mid-response, resetting the TCP connection. The proxy received a partial response that it cannot relay to the client.
How to Debug and Fix 502 Errors
Step 1: Check if the Backend is Running
# Check process status
systemctl status myapp # systemd service
pm2 status # PM2 managed Node.js
docker ps # Docker containers
supervisorctl status # Supervisor managed processes
# Check if the port is listening
ss -tlnp | grep 3000 # Is anything listening on port 3000?
lsof -i :3000 # What process is on port 3000?
# Try connecting directly to the backend
curl -v http://localhost:3000/health
Step 2: Check Nginx Error Logs
# Common Nginx 502 error messages:
# Backend is not running:
# "connect() failed (111: Connection refused) while connecting to upstream"
# Backend socket missing:
# "connect() failed (2: No such file or directory) while connecting to upstream"
# Backend crashed mid-response:
# "upstream prematurely closed connection while reading response header"
# Backend sent invalid response:
# "upstream sent invalid header while reading response header"
tail -50 /var/log/nginx/error.log
Step 3: Common Fixes
# Restart the backend application
systemctl restart myapp
pm2 restart all
docker restart my-container
# Fix Nginx proxy_pass configuration
# Verify the port matches the application
upstream backend {
server 127.0.0.1:3000; # Must match app's listening port
keepalive 32;
}
server {
location / {
proxy_pass http://backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
# Increase PHP-FPM workers if pool is exhausted
# /etc/php/8.2/fpm/pool.d/www.conf
pm = dynamic
pm.max_children = 50 # Increase from default 5
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
# Fix buffer size issues (Nginx)
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
Cloudflare-Specific 502
# If Cloudflare shows its own 502 error page:
# The issue is between Cloudflare and your origin server.
# Check that your origin server is reachable:
curl -v --resolve example.com:443:YOUR_ORIGIN_IP https://example.com
# Temporarily bypass Cloudflare (DNS only mode, orange cloud off)
# to test if the origin itself works
# Check Cloudflare system status: https://www.cloudflarestatus.com
For Regular Users
- Refresh the page: 502 errors are often temporary, lasting only seconds during a server restart or deployment. Wait 10-30 seconds and try again.
- Check if the site is down for everyone: Use a tool like downforeveryoneorjustme.com to see if others are also experiencing the issue.
- Try a different browser or device: If the issue persists, try accessing from your phone's mobile data (different network) to rule out local network issues.
- Clear DNS cache: On rare occasions, a stale DNS entry can cause your requests to go to the wrong server. Flush your DNS cache and try again.
Frequently Asked Questions
What causes a 502 Bad Gateway error?
A 502 occurs when a proxy/gateway server (Nginx, load balancer, CDN) tries to forward your request to a backend server but receives an invalid response or no response at all. The most common cause is the backend application being down — it crashed, ran out of memory, or is not running. Other causes: wrong port configuration, PHP-FPM pool exhausted, or network issues between proxy and backend.
How do I fix a 502 Bad Gateway error?
Check if the backend service is running (
systemctl status, pm2 status, docker ps). If it is down, restart it. Check Nginx error logs for the specific error message — it will tell you exactly why (connection refused, socket missing, premature close). Verify that the proxy_pass port matches the application's listening port. If PHP: check PHP-FPM status and increase worker count if needed.What is the difference between 502 and 504?
502 = bad response. The proxy connected to the upstream but got an invalid, incomplete, or no response (connection refused or reset). 504 = timeout. The proxy connected but the upstream took too long to respond. 502 is often about crashes or connection issues; 504 is about slow responses or hung processes.