# 502 Bad Gateway: upstream server unreachable

- **ID:** `api/http-502-bad-gateway-upstream-unreachable`
- **Domain:** api
- **Category:** network_error
- **Verification:** ai_generated
- **Fix Rate:** 85%

## Root Cause

The API gateway or reverse proxy received an invalid response from the upstream server, often due to the upstream being down, overloaded, or misconfigured in the load balancer.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Nginx 1.24+ | active | — | — |
| HAProxy 2.8+ | active | — | — |
| AWS ALB (2024) | active | — | — |

## Workarounds

1. **Check upstream server health via a health check endpoint (e.g., `/health`). Example: `curl -I http://upstream-service:8080/health`. If it fails, restart the upstream service or check its logs.** (90% success)
   ```
   Check upstream server health via a health check endpoint (e.g., `/health`). Example: `curl -I http://upstream-service:8080/health`. If it fails, restart the upstream service or check its logs.
   ```
2. **Verify load balancer configuration, ensuring the upstream server is correctly listed and the port matches. Example: `nginx -t` to test Nginx config, then `systemctl reload nginx`.** (85% success)
   ```
   Verify load balancer configuration, ensuring the upstream server is correctly listed and the port matches. Example: `nginx -t` to test Nginx config, then `systemctl reload nginx`.
   ```
3. **Temporarily bypass the gateway by hitting the upstream directly (if network permits) to isolate the issue. Example: `curl http://10.0.1.5:8080/api/v1/resource`.** (80% success)
   ```
   Temporarily bypass the gateway by hitting the upstream directly (if network permits) to isolate the issue. Example: `curl http://10.0.1.5:8080/api/v1/resource`.
   ```

## Dead Ends

- **** — The upstream server itself is unhealthy; restarting the gateway does not fix the upstream issue. (90% fail)
- **** — If the upstream is down, timeouts only delay failure detection; the root cause (e.g., crashed service) remains. (75% fail)
- **** — While DNS can cause this, the error often stems from upstream service failure (e.g., port 8080 not listening), not DNS resolution. (60% fail)