How to Fix Nginx 502 Bad Gateway: A Complete Troubleshooting Guide

Understanding the Nginx 502 Bad Gateway Error

When Nginx is configured as a reverse proxy or load balancer, it acts as a middleman between the client (user's browser) and the upstream backend server (such as a Node.js application, Python Gunicorn/uWSGI, or PHP-FPM). A 502 Bad Gateway error indicates that Nginx attempted to communicate with the upstream server, but the upstream server either rejected the connection, abruptly dropped it, or returned an invalid response.

While the 502 error is the most common, it belongs to a family of proxy-related status codes that share similar diagnostic paths:

• 502 Bad Gateway: The upstream server refused the connection or returned an invalid response.
• 503 Service Unavailable: The server is temporarily unable to handle the request, often due to planned maintenance, rate limiting, or resource exhaustion.
• 504 Gateway Timeout: Nginx successfully connected to the upstream, but the upstream failed to return a complete response within the configured timeout window.

Step 1: The Golden Rule - Check the Error Logs

Before making any configuration changes, you must consult the Nginx error logs. The access log will only show the HTTP 502 status, but the error log will provide the exact low-level socket or network error.

Run the following command to tail the error log:

tail -n 50 -f /var/log/nginx/error.log

You are looking for log entries that look like this:

Example 1: Connection Refused 2023/10/26 14:32:10 [error] 12345#0: *6789 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.50, server: example.com, request: "GET / HTTP/1.1", upstream: "http://127.0.0.1:3000/"

Example 2: Unix Socket Missing 2023/10/26 14:35:22 [error] 12345#0: *6792 connect() to unix:/var/run/php/php8.1-fpm.sock failed (2: No such file or directory) while connecting to upstream

Example 3: Connection Timed Out 2023/10/26 14:40:05 [error] 12345#0: *6801 upstream timed out (110: Connection timed out) while reading response header from upstream

Step 2: Diagnosing 'Connection Refused' (111)

The (111: Connection refused) error is the most frequent cause of a 502 Bad Gateway. It simply means Nginx tried to open a TCP connection to the upstream IP and port (e.g., 127.0.0.1:3000), but nothing is listening there.

Root Causes & Fixes:

1. The upstream service is dead/crashed: Check the status of your backend application. If you are running a Node.js app via PM2 or systemd, verify it's active: systemctl status my-node-app or pm2 status. If it crashed, restart it and check its specific logs to find out why it died.
2. The upstream service is booting up: If you just deployed new code or restarted the server, the backend might take a few seconds to bind to the port. If requests hit Nginx during this window, they get a 502.
3. Wrong Port Configuration: Nginx is configured to proxy_pass http://127.0.0.1:3000;, but your application is actually listening on port 8080. Verify the listening ports using: ss -tulpn | grep LISTEN.
4. Localhost vs. IP Binding: Nginx is trying to hit 127.0.0.1, but your dockerized app or backend is bound specifically to a public IP or a different network interface (like 0.0.0.0).

Step 3: Diagnosing Unix Socket Issues

If you use PHP-FPM or Gunicorn over Unix sockets (e.g., fastcgi_pass unix:/run/php/php8.1-fpm.sock;), 502 errors often stem from file system issues rather than network issues.

Root Causes & Fixes:

1. Socket file doesn't exist: The backend service isn't running, or it's configured to listen on a TCP port instead of a socket. Check your FPM pool config (/etc/php/8.1/fpm/pool.d/www.conf) and ensure the listen directive matches Nginx exactly.
2. Permissions issues: Nginx (usually running as www-data or nginx user) does not have read/write permissions to the socket file. The Nginx error log will show (13: Permission denied). Ensure the upstream service creates the socket with the correct ownership (e.g., listen.owner = www-data and listen.group = www-data in PHP-FPM).

Step 4: Resolving Nginx 504 Gateway Timeout

A 504 Gateway Timeout occurs when Nginx connects to the upstream successfully, sends the request, but the upstream application takes too long to generate the response. Nginx eventually gives up and drops the connection to prevent tying up worker processes.

How to Fix:

1. Optimize the Backend: This is the ideal solution. A request taking 60+ seconds is usually a symptom of a missing database index, an external API hanging, or an infinite loop in the code.

2. Increase Nginx Timeouts: If the long request is intentional (e.g., generating a massive PDF report), you need to tell Nginx to wait longer. Add or increase the following directives in your location block:

   location /report/ {
       proxy_pass http://backend;
       proxy_connect_timeout 60s;
       proxy_send_timeout 300s;
       proxy_read_timeout 300s;
   }
   

   Note: For FastCGI (PHP), use fastcgi_read_timeout 300s; instead.

Step 5: Fixing Connection Reset by Peer (104)

The Nginx log error recv() failed (104: Connection reset by peer) means the upstream server forcefully closed the TCP connection while Nginx was still waiting for data.

This usually indicates severe resource exhaustion on the backend. For example, if a PHP-FPM child process hits its memory limit or execution time limit, the master process will brutally kill it. When the process dies, the socket is torn down, and Nginx receives a TCP RST packet. You must investigate the memory limits and error logs of the backend application itself (e.g., /var/log/php8.1-fpm.log).

Step 6: Nginx SSL Handshake Failed

When Nginx acts as a reverse proxy over HTTPS (e.g., proxy_pass https://backend.internal;), it must negotiate an SSL/TLS connection with the upstream.

Errors like SSL_do_handshake() failed (SSL: error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure) occur due to:

1. SNI Mismatch: Nginx needs to send the Server Name Indication so the upstream knows which certificate to present. Add proxy_ssl_server_name on; to your location block.
2. Untrusted Upstream Certificate: If the upstream uses a self-signed certificate, Nginx will reject it by default if verification is enabled. You can either provide the CA cert using proxy_ssl_trusted_certificate /path/to/ca.crt; or, less securely, disable verification (if operating on a trusted internal network).
3. Protocol Mismatch: Nginx and the upstream share no common TLS protocols or ciphers (e.g., the upstream only supports TLS 1.3, but Nginx proxy settings are restricting it to TLS 1.2).