How to Fix 502 Bad Gateway Errors in Nginx, OpenLiteSpeed, and PHP-FPM

Understanding the Mechanics of a 502 Bad Gateway Error

The HTTP 502 Bad Gateway response code is one of the most common and disruptive errors encountered by server administrators. In simple terms, a 502 error occurs when your edge reverse proxy (such as Nginx, OpenLiteSpeed, Apache, or Cloudflare) acts as an intermediary gateway to an upstream application backend (such as PHP-FPM, Node.js, Gunicorn, or an upstream microservice) and receives an invalid, corrupted, or null response from that backend.

Unlike 500 Internal Server Error (which usually indicates an unhandled script exception within application code) or 504 Gateway Timeout (which means the upstream backend took too long to finish), a 502 Bad Gateway almost always signifies that the upstream backend crashed, terminated abnormally, ran out of worker processes, or failed to communicate over its designated Unix domain socket or TCP port.

Step 1: Inspecting Server Error Logs for Root Cause Identification

Never guess the source of a 502 error. Your server logs record the exact timestamp, socket file, and error condition. Check the primary web server and PHP-FPM error logs immediately:

# Inspect Nginx error log in real-time
sudo tail -n 50 -f /var/log/nginx/error.log

# Inspect PHP-FPM daemon error log
sudo tail -n 50 -f /var/log/php8.3-fpm.log

# Inspect systemd journal for kernel OOM (Out of Memory) kills
sudo journalctl -xeu php8.3-fpm --no-pager
sudo dmesg -T | grep -i "oom"

Common Root Cause 1: PHP-FPM Service Stopped or Socket Mismatch

The most frequent cause of 502 Bad Gateway in Nginx is a stopped PHP-FPM service or an incorrect socket path in your virtual host configuration block. If Nginx points to /run/php/php8.2-fpm.sock but the server upgraded to PHP 8.3, Nginx will fail to connect:

# Verify which PHP-FPM service is currently active
sudo systemctl status php*-fpm

# Check active Unix socket listeners
ls -la /run/php/

# If PHP-FPM is dead, restart and enable it
sudo systemctl restart php8.3-fpm
sudo systemctl enable php8.3-fpm

Ensure your Nginx configuration fastcgi_pass directive matches the active socket file:

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    # Must match the exact running socket
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}

Common Root Cause 2: PHP-FPM Worker Pool Exhaustion (pm.max_children)

Under heavy web traffic or during search engine indexing spikes, if all available PHP-FPM worker processes are busy processing long-running queries, incoming requests queue up. When the queue overflows, PHP-FPM rejects new connections, causing Nginx to emit a 502 Bad Gateway error with log messages like server reached pm.max_children setting.

To resolve worker starvation, edit your pool configuration in /etc/php/8.3/fpm/pool.d/www.conf:

# Calculate pm.max_children based on available RAM:
# Available RAM for PHP (e.g. 2048MB) / Average Process Size (e.g. 45MB) = ~45 max_children
pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 15
pm.max_requests = 1000

The pm.max_requests = 1000 directive prevents gradual memory leaks by recycling worker processes after handling 1,000 requests.

Common Root Cause 3: FastCGI Buffer Overflows (Headers Too Large)

When running complex CMS platforms like WordPress or Drupal with plugins that output large HTTP response headers or voluminous cookie sets, Nginx’s default 4KB buffer will truncate the upstream header and trigger upstream sent too big header while reading response header from upstream. Fix this by expanding FastCGI buffers in /etc/nginx/nginx.conf or within your server block:

# Expand FastCGI buffers in Nginx server block
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    
    # Optimized FastCGI Buffers
    fastcgi_buffer_size 128k;
    fastcgi_buffers 256 16k;
    fastcgi_busy_buffers_size 256k;
    fastcgi_temp_file_write_size 256k;
    fastcgi_read_timeout 300;
}

Common Root Cause 4: Linux OOM-Killer Terminating Backends

If your VPS runs out of physical memory, the Linux kernel Out-Of-Memory (OOM) killer automatically terminates the highest memory-consuming process (often MySQL or PHP-FPM). You can verify this by checking dmesg -T | grep -i killed. To prevent this permanently:

• Create a 2GB to 4GB swap partition using fallocate -l 2G /swapfile.
• Tune memory_limit in /etc/php/8.3/fpm/php.ini to reasonable boundaries (e.g., 256M or 512M per script, not -1).
• Enable Redis object caching to reduce database query overhead.

502 Bad Gateway Diagnostic Matrix