HTTP 502 Bad Gateway — What It Means and How to Fix It

What causes this error

HTTP 502 is a proxy-layer error meaning the reverse proxy successfully connected to the upstream server but received a response that was invalid, malformed, or an abrupt connection close (crash). Common causes: the backend process crashed and isn't listening, the backend is starting up and not yet ready, the wrong port is configured in the proxy, the backend sent an invalid HTTP response, or the backend hit an OOM and was killed by the OS.

How to fix it

1. 01

   step 1

   Test the backend directly, bypassing the proxy

   If the backend is reachable directly but the proxy gives 502, the issue is in the proxy configuration. If the backend is unreachable directly, the issue is the backend itself — crashed or not listening.

   # Test backend directly (on the server machine, bypassing Nginx/ALB)
   curl -si http://localhost:3000/health
   curl -si http://127.0.0.1:8080/
   
   # If this works but public URL gives 502 → proxy misconfiguration
   # If this fails → backend is down

   Copy
2. 02

   step 2

   Check and restart the backend process

   A crashed Node.js, Python, or Go process leaves nothing listening on the port. The proxy correctly reports 502. Use your process manager to check status and restart.

   # PM2
   pm2 status
   pm2 restart my-app
   pm2 logs --err --lines 50
   
   # systemd
   systemctl status my-service
   systemctl restart my-service
   journalctl -u my-service -n 100 -f
   
   # Docker
   docker ps -a  # check if container exited
   docker logs <container_id> --tail 50
   docker restart <container_id>

   Copy
3. 03

   step 3

   Verify the proxy's upstream port matches the backend

   A common misconfiguration: the proxy is pointing at port 3000 but the app was changed to listen on port 8080 (or vice versa). Check both the proxy config and the app's PORT environment variable.

   # Check Nginx upstream config
   cat /etc/nginx/sites-enabled/myapp
   # upstream backend { server 127.0.0.1:3000; }  ← must match app's listening port
   
   # Check what port the app is actually on
   ss -tlnp | grep node

   Copy
4. 04

   step 4

   Check for OOM kills

   The Linux OOM killer terminates processes when memory is exhausted — it leaves no application-level log. Check `dmesg` for OOM kill entries.

   # Check for OOM kills
   dmesg | grep -i 'oom\|killed' | tail -20
   
   # Check current memory usage
   free -h
   cat /proc/meminfo | grep MemAvailable

   Copy
5. 05

   step 5

   For AWS ALB/Cloudflare: check backend health check status

   AWS ALB removes unhealthy targets from the pool and returns 502 when no healthy targets remain. Check the target group's health check in the AWS console. Cloudflare 502 means your origin is unreachable or returning an invalid response.

   # AWS — check target health from CLI
   aws elbv2 describe-target-health \
     --target-group-arn arn:aws:elasticloadbalancing:...:targetgroup/...
   
   # Cloudflare — check if origin responds directly
   curl -si https://your-origin-ip/health -H 'Host: yourdomain.com'

   Copy

How to verify the fix

• Backend health endpoint returns 200 directly (bypassing proxy).
• Public URL returns a 2xx response.
• ALB target group shows all targets as Healthy.