Fix Nginx 502 Bad Gateway Upstream Error

Symptoms

Users see a white page with '502 Bad Gateway' when visiting the site. The browser displays the error code 502. Server logs show 'upstream prematurely closed connection' or 'connect() failed (111: Connection refused)'. The site may work intermittently or fail completely.

Root Causes

Common Triggers

• PHP-FPM service stopped or crashed – The most frequent cause. PHP-FPM processes die due to memory limits or errors.
• Upstream server timeout – Backend server (e.g., Node.js, Python, or another Nginx) takes too long to respond.
• Misconfigured socket or port – Nginx tries to connect to a Unix socket or TCP port that doesn't exist or has wrong permissions.
• Resource exhaustion – High traffic or memory leaks cause upstream processes to fail.
• Firewall or network issues – Upstream server is blocked by firewall or network outage.

Step-by-Step Fix

Step 1: Check Nginx Error Logs

tail -f /var/log/nginx/error.log

Look for lines containing 'upstream' or 'connect() failed'. This tells you which upstream server is problematic.

Step 2: Verify PHP-FPM Status (If Using PHP)

systemctl status php7.4-fpm   # or php8.1-fpm, php8.2-fpm

If inactive, restart it: systemctl restart php7.4-fpm. Check for errors: journalctl -u php7.4-fpm -n 50.

Step 3: Test Upstream Socket or Port

For Unix socket: ls -la /var/run/php/php7.4-fpm.sock. Ensure it exists and has correct permissions (usually 666 or owned by www-data). For TCP: netstat -tlnp | grep :9000 to confirm the port is listening.

Step 4: Increase Timeout Settings

Edit your Nginx site config (e.g., /etc/nginx/sites-available/example.com):

proxy_connect_timeout 75s;
proxy_send_timeout 600s;
proxy_read_timeout 600s;
fastcgi_read_timeout 600s;

Reload Nginx: systemctl reload nginx.

Step 5: Restart All Services

systemctl restart nginx
systemctl restart php7.4-fpm   # adjust version

Alternative Fixes

1. Increase PHP memory limit – Edit php.ini: memory_limit = 256M or higher.
2. Check for firewall rules – Ensure upstream port (e.g., 9000, 3000) is open: ufw status or iptables -L.
3. Use a different upstream method – Switch from socket to TCP (or vice versa) in your Nginx config.
4. Monitor resource usage – Use top or htop to check CPU/memory; add more workers if needed.
5. Update Nginx and PHP-FPM – Older versions may have bugs. Run apt update && apt upgrade (Debian/Ubuntu).

Prevention

• Set up monitoring (e.g., Nagios, Prometheus) to alert on upstream failures.
• Configure automatic service restart via systemd: Restart=always in service files.
• Implement health checks in Nginx using ngx_http_upstream_module.
• Regularly review logs for slow queries or memory leaks.
• Use a reverse proxy with multiple upstream servers for redundancy.

By following these steps, you can quickly resolve Nginx 502 errors and prevent future occurrences.