Why Does Nginx Return 502 Bad Gateway? A Complete Log‑to‑FastCGI Timeout Diagnosis

1. Symptom

Intermittent 502 Bad Gateway responses when accessing the site.

Nginx error log shows messages such as:

[error] 1234#0: *5678 recv() failed (104: Connection reset by peer) while reading response header from upstream

Problem occurs frequently under peak traffic and rarely under low load.

2. Definition of 502

The 502 Bad Gateway status means Nginx, acting as a reverse proxy, failed to communicate with an upstream server (backend, FastCGI, or PHP‑FPM). Typical causes are:

Backend service unavailable or malfunctioning.

Backend processing timeout.

Improper Nginx timeout configuration (e.g., proxy_read_timeout, fastcgi_read_timeout).

Network or connection anomalies.

3. Log Investigation

recv() failed

– upstream timed out; backend did not respond in time. connect() failed – backend could not establish a connection. 502 with FastCGI stderr – PHP‑FPM or FastCGI error.

4. Upstream Configuration Check

Example Nginx upstream block:

upstream backend {
    server 127.0.0.1:9000;
    keepalive 32;
}

Verify server IP and port are correct.

Ensure the keepalive value is reasonable.

Choose a load‑balancing method that matches the workload (e.g., least_conn or ip_hash).

5. FastCGI / PHP‑FPM Timeout Analysis

5.1 Nginx FastCGI Settings

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_connect_timeout 5s;
    fastcgi_send_timeout 30s;
    fastcgi_read_timeout 30s;
}

fastcgi_read_timeout defines the maximum time Nginx waits for a response from the backend.

5.2 PHP‑FPM Settings

request_terminate_timeout = 30s
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 20

5.3 Common Timeout Causes

Slow PHP scripts (inefficient SQL or blocked external calls).

FastCGI / PHP‑FPM connections being reset.

High concurrency hitting the pm.max_children limit.

Nginx timeout values shorter than PHP‑FPM execution time.

6. Practical Troubleshooting Steps

Inspect Nginx error log: tail -f /var/log/nginx/error.log Enable and check PHP‑FPM slow log (set request_slowlog_timeout = 5s and slowlog = /var/log/php-fpm/slow.log). cat /var/log/php-fpm/slow.log Monitor backend load:

top
netstat -anp | grep 9000

Test endpoint response: curl -I http://127.0.0.1/index.php Verify pm.max_children capacity:

ps aux | grep php-fpm

7. Solutions and Optimization

7.1 Adjust Nginx Timeouts

fastcgi_connect_timeout 5s;
fastcgi_send_timeout 60s;
fastcgi_read_timeout 60s;

7.2 Adjust PHP‑FPM Parameters

pm.max_children = 100
request_terminate_timeout = 60s

7.3 Application Performance Tuning

Add indexes to slow SQL queries.

Avoid long‑running external API calls.

Cache hot data to reduce PHP execution time.

7.4 Monitoring and Alerting

Enable Nginx and PHP‑FPM slow‑request logging.

Use Prometheus/Grafana to monitor response times, active processes, and connection counts.

8. Advanced Debugging Techniques

Trace PHP‑FPM system calls:

strace -p <code>php-fpm-pid</code> -e trace=network,write,read

Capture traffic on the loopback interface: tcpdump -i lo port 9000 Reproduce the issue with a load test: ab -n 1000 -c 50 http://127.0.0.1/index.php Enable Nginx debug logging:

error_log /var/log/nginx/error.log debug;

9. Common Misconceptions

Increasing Nginx timeout solves everything. Backend PHP may still be slow; optimize code and SQL.

Setting pm.max_children too high. Can exhaust memory and cause OOM; calculate a safe value based on server resources.

Too many keepalive connections. PHP‑FPM cannot handle many long‑lived connections; keep the number moderate.

Ignoring the slowlog. Misses slow requests; enable and analyze the slowlog regularly.

10. Real‑World Case Study

Background: High‑traffic e‑commerce site experiencing frequent 502 errors during peak load.

Log sample:

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

Investigation: Confirmed Nginx and PHP‑FPM configurations; identified several SQL queries taking 5‑10 seconds.

Changes applied:

Set fastcgi_read_timeout to 60 s.

Increased pm.max_children to 80.

Optimized SQL queries and added caching.

Result: 502 errors dropped dramatically; response times stabilized at 100‑300 ms.

11. Capacity Planning Recommendations

Calculate pm.max_children as: total RAM ÷ memory per PHP‑FPM process ÷ safety factor.

Keep Nginx and PHP‑FPM timeout values consistent.

Monitor active connections and slow‑request metrics.

Cache hot endpoints or handle them asynchronously.

Run regular load tests and adjust configuration dynamically.

12. Summary

502 Bad Gateway usually signals backend failures or timeouts.

Log analysis, slow‑request inspection, and matching timeout settings are essential.

High‑concurrency environments need capacity planning, performance tuning, and continuous monitoring.

Avoid merely increasing timeouts or pm.max_children without addressing underlying application issues.