How to Fix 502 Bad Gateway in Nginx on Ubuntu 24.04 LTS
Quick Fix Summary
TL;DRRestart your upstream application server and verify Nginx can connect to it on the correct port.
A 502 Bad Gateway error indicates Nginx, acting as a reverse proxy, cannot successfully communicate with its configured upstream server (e.g., Gunicorn, PHP-FPM, Node.js). This is a critical failure in the request-handling pipeline.
Diagnosis & Causes
Recovery Steps
Step 1: Verify Upstream Server Status
First, confirm your backend application (e.g., Gunicorn, PHP-FPM) is actively running and listening on the expected port or socket.
sudo systemctl status your-app-service
sudo ss -tlnp | grep :8000
curl -I http://localhost:8000/healthStep 2: Check Nginx Error Logs for Specifics
Nginx error logs provide the exact reason for the upstream failure. Tail the logs in real-time to see connection errors, timeouts, or permission denials.
sudo tail -f /var/log/nginx/error.log
sudo journalctl -u nginx -f --no-pagerStep 3: Test Network Connectivity to Upstream
Manually test if Nginx can reach the upstream server from the server itself, bypassing the web layer.
curl -v http://127.0.0.1:8000
telnet 127.0.0.1 8000
sudo ufw status verboseStep 4: Review and Validate Nginx Site Configuration
Inspect your Nginx configuration for the `proxy_pass` directive, ensuring the upstream address and port are correct. Look for syntax errors.
sudo nginx -t
sudo cat /etc/nginx/sites-available/your-siteStep 5: Adjust Nginx Upstream Timeout and Buffer Settings
If the upstream is slow, increase Nginx's timeout and buffer parameters in the `location` or `http` block to prevent premature 502 errors.
location / {
proxy_pass http://127.0.0.1:8000;
proxy_connect_timeout 75s;
proxy_send_timeout 75s;
proxy_read_timeout 75s;
proxy_buffers 8 16k;
proxy_buffer_size 32k;
}Step 6: Restart/Rollback and Monitor
Restart services in the correct order and monitor logs. If the error persists after a recent change, consider a rollback.
sudo systemctl restart your-app-service
sudo systemctl reload nginx
sudo tail -f /var/log/nginx/error.log /var/log/your-app.logArchitect's Pro Tip
"For PHP-FPM pools, a 502 often means the pool is saturated (`pm.max_children`). Check `pm.status_path` and use `curl` to monitor active/max children in real-time."
Frequently Asked Questions
I fixed it, but the 502 error comes back after a few minutes. What's happening?
This indicates a recurring upstream failure. Your application server is likely crashing due to a memory leak, unhandled exception, or being overwhelmed by traffic. Check application logs and monitor system resources (RAM, CPU).
Should I use `reload` or `restart` for Nginx after a config change?
Always use `sudo nginx -t` to test first. Then use `sudo systemctl reload nginx`. This loads the new configuration gracefully without dropping connections. Use `restart` only if `reload` fails or the service is unresponsive.
My upstream server is on a different host. How do I troubleshoot?
The principles are the same. Verify network connectivity (firewalls, security groups, routes), ensure the remote service is listening on its network interface (not just 127.0.0.1), and double-check the `proxy_pass` URL in Nginx points to the correct remote IP/hostname and port.