Nginx: 502 Bad Gateway

Nginx returns a 502 Bad Gateway error when it cannot establish a valid connection to the upstream backend server such as PHP-FPM, Node.js, or a proxied application.

The 502 Bad Gateway error may appear as:

• 502 Bad Gateway
• 502 Bad Gateway NGINX
• HTTP Error 502 - Bad Gateway
• 502 Proxy Error
• Temporary Error (502)

When Nginx Produces the 502 Bad Gateway Error

Nginx produces the 502 Bad Gateway error when it forwards a client request to an upstream backend and receives an invalid response or no response at all. This happens when Nginx acts as a reverse proxy with proxy_pass or when it communicates with PHP-FPM through fastcgi_pass.

Nginx also returns a 502 Bad Gateway when the upstream server process has crashed, the Unix socket file is missing, or the TCP port is not listening. The error appears in the browser as a 502 status page and in the Nginx error log with details about the failed upstream connection.

What Causes the 502 Bad Gateway Error in Nginx

Nginx returns 502 when PHP-FPM is not running.The PHP-FPM service must be active to process PHP requests. If PHP-FPM has crashed, been stopped, or failed to start after a reboot, Nginx has no backend to forward requests to. The Nginx error log shows connect() failed (111: Connection refused) or no live upstreams when this occurs.

Nginx returns 502 when the socket path in nginx.conf does not match PHP-FPM.The fastcgi_pass directive in nginx.conf must point to the same Unix socket or TCP port that PHP-FPM listens on. A mismatch causes Nginx to connect to a nonexistent socket, which triggers the 502 error. The Nginx error log shows connect() to unix:/var/run/php-fpm.sock failed (2: No such file or directory) when the socket file does not exist.

Nginx returns 502 when the upstream server exhausts its worker processes.PHP-FPM has a limited pool of worker processes defined by the pm.max_children setting. When all workers are busy and cannot accept new connections, Nginx receives a connection refusal or timeout that results in a 502 error.

Nginx returns 502 when server resources (memory or CPU) are exhausted.A server under heavy load may not have enough memory for PHP-FPM to fork new worker processes. Swap usage, high CPU load averages, and out-of-memory (OOM) kills can all cause the upstream to become unresponsive.

How to Fix the 502 Bad Gateway Error in Nginx

1. Check whether PHP-FPM is running. Nginx cannot forward requests if the PHP-FPM service is stopped or crashed.

ps aux | grep php-fpm

If no PHP-FPM processes appear, start the service:

sudo systemctl enable php-fpm.service
sudo systemctl start php-fpm.service

The service name may differ depending on the PHP version. Use php8.2-fpm or php7.4-fpm on Debian and Ubuntu systems.

2. Verify that the socket path in nginx.conf matches the PHP-FPM configuration. Open nginx.conf and check the fastcgi_pass directive.

server {
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
    }
}

Confirm the socket file exists on disk:

ls -la /var/run/php/php8.2-fpm.sock

If the socket file does not exist, PHP-FPM is not running or is configured to listen on a different path. Check the PHP-FPM pool configuration at /etc/php/8.2/fpm/pool.d/www.conf for the listen directive.

3. Increase FastCGI buffer sizes and timeouts in nginx.conf if the backend is slow or returns large responses. Nginx returns a 502 when the upstream response exceeds the default buffer limits.

location ~ \.php$ {
    fastcgi_buffers 8 16k;
    fastcgi_buffer_size 32k;
    fastcgi_connect_timeout 60;
    fastcgi_send_timeout 300;
    fastcgi_read_timeout 300;
}

4. Test the nginx.conf configuration and reload Nginx.

sudo nginx -t
sudo systemctl reload nginx

5. Check the Nginx error log for specific connection failure details.

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

How to Verify the Fix

Nginx stops returning 502 errors when the upstream backend responds correctly. Send a test request and confirm a successful response:

curl -I http://example.com/

A 200 OK status code confirms that Nginx successfully connects to the upstream server. Monitor the Nginx error log for any recurring upstream connection failures.

Edge Cases and Variations

Nginx returns 502 behind a CDN such as Cloudflare.Cloudflare caches the 502 error page from Nginx and may continue serving it after the fix is applied. Purge the CDN cache after resolving the upstream issue. Temporarily bypass the CDN by pointing DNS directly to the origin server IP to confirm the fix.

Nginx returns 502 when the upstream uses a TCP port instead of a Unix socket.If PHP-FPM listens on 127.0.0.1:9000 instead of a socket file, the fastcgi_pass directive must use the TCP address. A firewall rule blocking port 9000 on the loopback interface causes the 502 error.

Nginx returns 502 after a PHP version upgrade.A PHP version upgrade changes the socket file path (e.g., from php7.4-fpm.sock to php8.2-fpm.sock). Update the fastcgi_pass directive in nginx.conf to match the new socket path.

Related Nginx Errors

Nginx: 504 Gateway Timeout-- Nginx returns a 504 when the upstream responds too slowly, while a 502 indicates the connection failed entirely or returned an invalid response.

Nginx: connect() to php-fpm.sock failed (Permission denied)-- A permission error on the Unix socket produces a 502 error with a different root cause.

Nginx downloads PHP files instead of executing them-- A missing fastcgi_pass directive causes Nginx to serve PHP files as downloads rather than processing them.