# 502 Bad Gateway: upstream connection reset by peer

- **ID:** `api/http-502-bad-gateway-upstream-connection-reset`
- **Domain:** api
- **Category:** network_error
- **Error Code:** `502`
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

The upstream server (e.g., application backend) abruptly closed the TCP connection while the proxy (e.g., NGINX, ALB) was trying to forward the request, often due to a crash, timeout, or firewall rule.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| NGINX 1.24+ | active | — | — |
| AWS ALB 2023+ | active | — | — |
| HAProxy 2.8+ | active | — | — |
| Gunicorn 21+ | active | — | — |
| uWSGI 2.0+ | active | — | — |

## Workarounds

1. **Check upstream server logs for application crashes or resource exhaustion. For example, in a Python Gunicorn setup, look for 'Worker failed to boot' or 'Out of memory'. Increase the number of workers or memory limits. Example command to add more workers:
gunicorn --workers=4 --timeout=120 myapp:app** (85% success)
   ```
   Check upstream server logs for application crashes or resource exhaustion. For example, in a Python Gunicorn setup, look for 'Worker failed to boot' or 'Out of memory'. Increase the number of workers or memory limits. Example command to add more workers:
gunicorn --workers=4 --timeout=120 myapp:app
   ```
2. **Verify firewall rules between proxy and upstream. On Linux, use iptables to check for dropped packets:
iptables -L -n -v | grep DROP
If rules are blocking, add an allow rule for the proxy IP on the upstream's port (e.g., port 8080).** (80% success)
   ```
   Verify firewall rules between proxy and upstream. On Linux, use iptables to check for dropped packets:
iptables -L -n -v | grep DROP
If rules are blocking, add an allow rule for the proxy IP on the upstream's port (e.g., port 8080).
   ```

## Dead Ends

- **** — The reset is immediate, not due to a slow response. (80% fail)
- **** — The upstream server is the root cause. (90% fail)