HTTP 502 Error: Bad Gateway

The HTTP 502 "Bad Gateway" error is a status code indicating that a server acting as a gateway or proxy received an invalid response from the upstream server to which it was forwarding the request. It's one of the most common 5xx errors in modern architectures using reverse proxies, load balancers, or CDNs.

Unlike the 504 (Gateway Timeout) where the upstream server doesn't respond at all, the 502 means the server did receive a response, but that response was invalid or incomprehensible. This can result from an application crash, a malformed HTTP response, or an unexpected connection closure.

For DevOps teams and system administrators, quickly understanding and resolving 502 errors is crucial. MoniTao monitors your endpoints continuously and alerts you as soon as a 502 error is detected, enabling rapid intervention before your users are massively impacted.

Common causes of 502 errors

The 502 error can have many origins, all related to communication between the proxy and the backend server:

• Crashed backend application: the PHP, Python, Node.js or other application has crashed or was killed by the system (OOM killer). The process manager (PHP-FPM, Gunicorn, PM2) has no more workers available to process requests.
• PHP-FPM or Gunicorn timeout: the worker timeout is reached before the application generates its response. The process manager kills the worker, abruptly closing the connection and generating a 502 on the proxy side.
• Saturated backend socket: the socket connections to the backend (TCP or Unix socket) are all in use or the listen backlog is exceeded. New connections are refused.
• Malformed HTTP response: the backend application returns a response that doesn't comply with HTTP protocol (invalid headers, corrupted content, incorrect encoding). The proxy cannot interpret the response.

Architectures where 502 occurs

Understanding where the proxy sits in your stack helps better diagnose the 502 origin:

• Nginx → PHP-FPM: classic LEMP configuration. The 502 occurs when PHP-FPM is stopped, overloaded, or when the PHP script crashes before generating a response.
• HAProxy → Backend: in load balancing, the 502 indicates that no backend in the pool could respond correctly. Check health checks and each backend's state.
• Cloudflare → Origin: Cloudflare generates a 502 when your origin server returns an invalid response. The Ray ID in the error helps with diagnosis.
• API Gateway → Microservice: in a microservices architecture, the 502 may indicate that a downstream service is in error. Trace the request to identify the faulty service.

Diagnosing 502 errors

A methodical diagnosis allows you to quickly identify the cause of the 502:

• Check backend processes: ensure PHP-FPM, Gunicorn or your application server is running (ps aux, systemctl status). Verify it's listening on the correct port or socket.
• Check logs: examine both proxy logs (Nginx error.log) AND application logs. Fatal PHP errors, segfaults, OOM kills are recorded there.
• Test backend directly: if possible, access the backend without going through the proxy (curl http://127.0.0.1:9000/). This isolates the problem between proxy and application.
• Check connections: use netstat or ss to see socket connection states. A large number of connections in TIME_WAIT or CLOSE_WAIT may indicate a problem.

Nginx configuration example to avoid 502

Good timeout and connection count configuration prevents many 502 errors:

# /etc/nginx/nginx.conf
upstream php_backend {
    server unix:/var/run/php/php8.2-fpm.sock;
    keepalive 32;  # Persistent connection pool
}

server {
    location ~ \.php$ {
        fastcgi_pass php_backend;
        fastcgi_connect_timeout 60s;
        fastcgi_send_timeout 60s;
        fastcgi_read_timeout 60s;

        # Buffer to avoid truncated responses
        fastcgi_buffer_size 32k;
        fastcgi_buffers 8 16k;

        # Retry on another backend if available
        fastcgi_next_upstream error timeout;
        fastcgi_next_upstream_tries 2;
    }
}

This configuration establishes a keepalive connection pool to PHP-FPM, defines appropriate timeouts, and configures sufficient buffers to avoid truncated responses.

Monitoring 502 errors with MoniTao

MoniTao offers several features to detect and respond to 502 errors:

• Automatic detection: each HTTP monitor captures the response code. A 502 immediately triggers the verification process.
• Double verification: to avoid false positives, MoniTao performs a second check after a configurable delay before sending the alert.
• Multi-channel alerts: receive alerts via email, SMS, Slack, or webhook based on your configuration and urgency.
• History and trends: analyze 502 error history to identify patterns (peak hours, after deployment, etc.).

Frequently asked questions about 502 errors

Conclusion

The HTTP 502 Bad Gateway error is a symptom of a communication problem between your proxy and your backend. Resolution requires methodical diagnosis: verify the backend is running, check logs, test direct connection, and adjust timeouts if necessary.

With MoniTao, you're alerted as soon as a 502 error occurs, allowing you to intervene before user impact becomes critical. Configure monitors on your sensitive endpoints and use history to identify recurring patterns.

Ready to Sleep Soundly?

Start free, no credit card required.

Create My Account See pricing