🌐
HTTP Status Error
HTTP 502 Bad Gateway
The reverse proxy server (Nginx/HAProxy/Traefik) received an invalid response from the upstream application server (Node.js/Gunicorn/PHP-FPM).
What This Error Means
A 502 Bad Gateway indicates that an edge or reverse proxy server received an invalid, corrupted, or null response from the backend application service it tried to reach.
The client successfully connected to the front-facing proxy, but the proxy could not communicate properly with the backend app process.
Why It Occurs
The backend application server crashed, rebooted, or ran out of memory (OOM).
The backend is not listening on the expected Unix socket or local TCP port.
A firewall or network policy is blocking communication between reverse proxy and upstream service.
Symptoms
- ⚠ Every request or intermittent requests return HTTP 502
- ⚠ Error logs in /var/log/nginx/error.log show "connect() failed (111: Connection refused)" or "upstream prematurely closed connection"
- ⚠ Upstream service restarts frequently
Common Causes
- • Backend Node.js, Python Gunicorn, or PHP-FPM process crashed due to unhandled exceptions
- • Process killed by Linux kernel OOM killer due to memory exhaustion
- • Unix domain socket permissions wrong (/run/php/php-fpm.sock owned by root instead of www-data)
- • Nginx proxy buffer size too small for large response headers
How to Fix It
- Check upstream service status: systemctl status myapp (or php-fpm, gunicorn)
- Inspect application logs for crashes: journalctl -u myapp --since "30m ago"
- Check kernel logs for OOM kills: dmesg -T | grep -i oom
- Verify socket permissions: ls -la /run/php/php-fpm.sock and chown www-data:www-data if needed
- Increase proxy buffer sizes in Nginx: proxy_buffer_size 128k; proxy_buffers 4 256k;
| Command | Purpose |
|---|---|
| systemctl status nginx myapp | Check service daemon states |
| ss -tulpn | grep LISTEN | Confirm backend port is listening |
| dmesg -T | grep -i oom | Check for out-of-memory killed processes |
| tail -n 50 /var/log/nginx/error.log | Inspect reverse proxy error log |
Verification
- ✓ Confirm backend application returns 200 OK directly using curl -I http://127.0.0.1:3000
- ✓ Verify public URL responds with 200 OK through the reverse proxy
Prevention
- → Run application behind process manager with auto-restart (systemd Restart=always or PM2)
- → Configure memory limits and alerting before containers run out of RAM