Nginx 502 Bad Gateway

Nginx 502 Bad Gateway

A 502 Bad Gateway from nginx means nginx received an invalid response (or no response) from the upstream server it is proxying to. The error is always in the backend, not in nginx itself. Nginx is working correctly — it is reporting that the backend (PHP-FPM, a Node.js app, a Java service, or another server) failed to respond properly. The diagnostic approach is the same regardless of backend: check nginx error logs first, then check the backend process.

What causes 502 errors

Diagnosing 502 errors

# Step 1: check nginx error log immediately:
sudo tail -50 /var/log/nginx/error.log

nginx error log showing 502 cause

2025/06/09 14:35:22 [error] 1234#1234: *456 connect() to unix:/var/run/php/php8.1-fpm.sock
failed (2: No such file or directory) while connecting to upstream,
client: 203.0.113.5, server: example.com, request: "GET / HTTP/1.1"

# "No such file or directory" for the socket = PHP-FPM is not running
# The socket file only exists while PHP-FPM is running

# Check if backend service is running:
sudo systemctl status php8.1-fpm    # For PHP-FPM
sudo systemctl status myapp         # For a custom application
sudo netstat -tlnp | grep :8080     # Check if port is listening

# Common 502 from PHP-FPM — start it:
sudo systemctl start php8.1-fpm
sudo systemctl status php8.1-fpm    # Confirm it stays running

# Verify socket exists:
ls -la /var/run/php/php8.1-fpm.sock

502 from PHP-FPM backend

# PHP-FPM socket permission issue (common after upgrades):
# nginx error: connect() to unix:/var/run/php/php8.1-fpm.sock failed (13: Permission denied)

# Fix: check socket permissions in PHP-FPM pool config:
grep -E "listen.(owner|group|mode)" /etc/php/8.1/fpm/pool.d/www.conf

Expected socket permission settings

listen.owner = www-data
listen.group = www-data
listen.mode = 0660    # Only owner and group can access the socket

# Verify nginx user:
grep "^user" /etc/nginx/nginx.conf    # Should be www-data or same as PHP-FPM socket owner

# Nginx user must match PHP-FPM socket owner/group
# After changing:
sudo systemctl reload php8.1-fpm
sudo systemctl reload nginx

502 from upstream application

# nginx proxying to Node.js/Java/Python app on port 8080:
sudo tail -f /var/log/nginx/error.log &
# Now make a request: curl http://example.com/api/endpoint

# If error is: upstream timed out (110)
# → Backend is running but responding too slowly
# Fix: increase timeout in nginx config:
sudo nano /etc/nginx/sites-available/example.com

nginx proxy timeout settings

location /api/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_read_timeout 60s;      # Wait up to 60s for response (default 60s)
    proxy_connect_timeout 10s;   # Wait up to 10s for connection
    proxy_send_timeout 60s;      # Wait up to 60s to send request
}

# Check application logs directly:
sudo journalctl -u myapp -f    # If systemd service
sudo tail -f /var/log/myapp/error.log

# Reload nginx after config change:
sudo nginx -t && sudo systemctl reload nginx

Conclusion

nginx error logs are the starting point for every 502 investigation — they contain the exact error message explaining what happened. The three most common root causes in production are: PHP-FPM not running (start it), PHP-FPM pool exhausted (increase max_children), or a slow backend timeout (fix the slow query/API call, or increase proxy_read_timeout as a temporary measure). Never increase timeouts without also fixing the root cause; a slow backend that takes 60 seconds instead of 5 will eventually exhaust nginx worker connections under load.