How to Fix HTTP 502 Bad Gateway Error

In this tutorial, you'll learn about How to Fix HTTP 502 Bad Gateway Error. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

The Problem

Your API client receives:

HTTP/1.1 502 Bad Gateway

The server acting as a gateway or proxy received an invalid response from the upstream server that it accessed in trying to fulfill the request.

Quick Fix

1. Check if the upstream server is running

The backend application that Nginx or Apache proxies to may be down:

# Check the backend service
sudo systemctl status myapp
sudo systemctl status gunicorn  # or uwsgi, pm2, etc.

# If down, restart it
sudo systemctl restart myapp

2. Test the upstream directly

Bypass the proxy and test the backend directly:

# If Nginx proxies to localhost:3000
curl -v http://127.0.0.1:3000/health

# Expected — a successful response from the backend

If the backend does not respond, the issue is with the application, not the proxy.

3. Check Nginx proxy configuration

# /etc/nginx/sites-available/myapp

# Wrong — wrong upstream address
location / {
    proxy_pass http://localhost:3001;  # backend is on 3000
}

# Right
location / {
    proxy_pass http://localhost:3000;
}

Always include these proxy headers:

location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

4. Check for upstream timeout

The backend may be responding too slowly:

# Increase proxy timeout
location /api/ {
    proxy_pass http://backend:3000;
    proxy_connect_timeout 60s;
    proxy_read_timeout 60s;
}

5. Check for buffer overflow

Large responses may exceed the proxy buffer:

# Increase buffer size for large responses
location / {
    proxy_buffers 8 16k;
    proxy_buffer_size 32k;
    proxy_busy_buffers_size 64k;
}

6. Restart the proxy and backend

sudo systemctl restart nginx
sudo systemctl restart myapp

Prevention

• Use health checks to monitor upstream server availability.
• Configure Nginx to detect and handle unhealthy upstreams.
• Set appropriate proxy timeouts and buffer sizes.
• Use a Process manager to auto-restart the backend if it crashes.
• Monitor 502 rates in your analytics or logging.

Common Mistakes with 502 bad gateway

1. Using head and tail instead of pattern matching, causing runtime errors on empty lists
2. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
3. Using return to exit a function early instead of wrapping a pure value in the monad

These mistakes appear frequently in real-world API code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ