How to Fix Nginx 502 Bad Gateway with PHP-FPM

You deploy a code update or experience a sudden surge in website traffic, and your web application immediately drops offline. Visitors are greeted by a generic white error page: 502 Bad Gateway - nginx. Neither your WordPress admin panel, Laravel routes, nor custom PHP scripts respond, leaving your online business inaccessible.

The Nginx 502 Bad Gateway error indicates that Nginx, acting as an edge reverse proxy or web server, received an invalid, corrupted, or non-existent response from the upstream processing daemon (in this case, PHP-FPM). Rather than being a failure in Nginx itself, a 502 error almost always signifies that the PHP backend service has crashed, run out of memory, timed out, or lacks socket permissions.

In this comprehensive sysadmin troubleshooting guide, we dissect the primary failure modes between Nginx and PHP FastCGI and provide tested configuration recipes to restore reliable uptime. If your company requires high-availability hosting or server hardening, learn more about our enterprise cloud hosting and DevOps solutions.

1. The Root Causes of Nginx 502 Bad Gateway

When an HTTP request arrives at Nginx for a dynamic PHP page, Nginx passes the FastCGI parameters over a UNIX domain socket (such as /run/php/php8.2-fpm.sock) or a local TCP loopback port (127.0.0.1:9000). A 502 error triggers when this upstream handshake fails:

• PHP-FPM Service Stopped: The PHP-FPM daemon has crashed due to an out-of-memory fatal error or segfault, leaving no process listening on the socket.
• Socket Permission Mismatches: The UNIX socket file is owned by root or www-data with permissions that prevent the Nginx user from reading and writing.
• Exhausted Max Children: Under heavy traffic spikes, all available PHP-FPM worker processes are busy, causing new connection requests to queue and time out.
• FastCGI Buffer Overflow: Upstream PHP response headers exceed the default buffer size allocated in the Nginx configuration.

2. Step-by-Step Fixes for PHP-FPM

Execute these diagnostics in your server terminal to isolate and resolve the issue:

Fix 1: Verify and Restart the PHP-FPM Daemon

Check if the PHP-FPM service is active. Replace 8.2 with your installed PHP version:

# Check PHP-FPM status
sudo systemctl status php8.2-fpm

# If stopped or inactive, start and enable the daemon
sudo systemctl restart php8.2-fpm
sudo systemctl restart nginx

Fix 2: Correct UNIX Socket Permissions

If your Nginx log shows connect() to unix:... failed (13: Permission denied), update the PHP-FPM pool configuration file (located at /etc/php/8.2/fpm/pool.d/www.conf):

; Ensure the socket is owned by the web server user
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

Save changes and restart PHP-FPM with sudo systemctl restart php8.2-fpm.

Fix 3: Expand FastCGI Buffer Limits in Nginx

If the error log reads upstream sent too big header while reading response header from upstream, your application is outputting large cookies, headers, or debug data. Add these buffer directives inside the location ~ \.php$ block of your Nginx server block:

fastcgi_buffer_size 128k;
fastcgi_buffers 256 16k;
fastcgi_busy_buffers_size 256k;
fastcgi_temp_file_write_size 256k;
fastcgi_read_timeout 300;

Validate Nginx configuration syntax before reloading to prevent server downtime according to official Nginx documentation:

sudo nginx -t
sudo systemctl reload nginx

3. Scaling PHP-FPM Worker Processes for High Traffic

If a 502 appears only during traffic spikes, your PHP process pool is starving for workers. Open /etc/php/8.2/fpm/pool.d/www.conf and tune process manager parameters based on your available server RAM:

pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 15
pm.max_requests = 500

4. Diagnostic Error Code Reference

For more web architecture strategies, read our comparison on fixing slow website load times. If you are experiencing persistent production errors and need hands-on assistance, reach out via our contact page.

5. Where to Go From Here

Resolving an Nginx 502 error requires checking the communication link between your reverse proxy and your backend PHP interpreter. To ensure your web infrastructure remains stable under continuous production workloads, follow these recommendations:

• Always test Nginx configurations with nginx -t before applying any reload command.
• Monitor PHP slow query logs by setting request_slowlog_timeout = 5s in your PHP-FPM pool configuration.
• Install system monitoring tools like Netdata or Prometheus to receive real-time alerts before your server runs out of memory.