Troubleshooting 502 Bad Gateway & 504 Gateway Timeout Errors in Nginx and PHP-FPM

Troubleshooting 502 Bad Gateway & 504 Gateway Timeout Errors in Nginx and PHP-FPM

Author: Mir Alamin (Principal Web Architect) | Published: July 20, 2026 at 11:50 AM | Reading Time: 20 min read | Category: Maintenance | Tags: Nginx, PHP Tune, Troubleshooting, Web Server, Maintenance

---

Executive Summary

HTTP 502 Bad Gateway and 504 Gateway Timeout errors are among the most frustrating issues facing system administrators. In LEMP environments, a 502 Bad Gateway indicates that Nginx received an invalid or terminated response from the upstream PHP-FPM pool socket, while a 504 Gateway Timeout means PHP-FPM failed to respond before Nginx's fastcgi_read_timeout expired.

This diagnostic field guide provides systematic steps for analyzing error logs, tuning socket backlogs, increasing timeout thresholds, and resolving PHP worker crashes.

---

1. Root Causes of 502 Bad Gateway Errors in PHP-FPM

When Nginx returns a 502 Bad Gateway error, examine /var/log/nginx/error.log:

Common Log Signature 1: Socket Permission / File Missing

connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory)

Fix: Verify that PHP-FPM service is running (sudo systemctl status php8.3-fpm) and that socket paths in Nginx match /etc/php/8.3/fpm/pool.d/www.conf.

Common Log Signature 2: Worker Process Crash (Segmentation Fault)

recv() failed (104: Connection reset by peer) while reading response header from upstream

Fix: A PHP script exhausted memory_limit or triggered an unhandled extension segmentation fault. Inspect /var/log/php8.3-fpm.log to identify the failing script.

---

2. Resolving 504 Gateway Timeout Errors

A 504 Gateway Timeout occurs when long-running PHP scripts (such as database imports, image processing, or API webhooks) exceed Nginx read timeouts.

Increasing FastCGI Timeouts in Nginx:

# /etc/nginx/sites-available/example.conf
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;

    # Increase timeout thresholds from default 60s to 300s
    fastcgi_read_timeout 300s;
    fastcgi_send_timeout 300s;
    fastcgi_connect_timeout 60s;
}

Match Timeouts in /etc/php/8.3/fpm/php.ini:

max_execution_time = 300
max_input_time = 300
memory_limit = 512M

---

3. Tuning Socket Backlog Limits (listen.backlog)

When incoming request bursts exceed the PHP-FPM socket queue, Nginx drops connections with 502 errors.

; /etc/php/8.3/fpm/pool.d/www.conf
listen.backlog = 65535

Kernel sysctl adjustment:

sudo sysctl -w net.core.somaxconn=65535

---

4. Emergency Diagnostic & Troubleshooting Services

If your web server is experiencing recurring 502/504 errors, performance degradation, or crashes:

• 🔧 Website & Server Troubleshooting Services
• ⚙️ Managed Server Administration Plans

---

5. Frequently Asked Questions (FAQ)

Q1: What is the difference between 502 and 504 errors?

502 Bad Gateway means Nginx reached the backend server (PHP-FPM) but received an invalid response or connection reset. 504 Gateway Timeout means Nginx reached the backend, but the backend took too long to finish processing the request.

Q2: How do I find slow PHP scripts causing 504 timeouts?

Enable the PHP-FPM slow log in /etc/php/8.3/fpm/pool.d/www.conf: set request_slowlog_timeout = 5s and inspect /var/log/php8.3-fpm.slow.log.

---

© 2026 WebCare Pro. Authored by Mir Alamin.