Resolving 502 Bad Gateway Errors in Nginx + PHP‑FPM + MySQL Environments

When configuring a Linux server with Nginx, PHP‑FPM, and MySQL, the site may initially work but later return a 502 Bad Gateway error, usually caused by issues in FastCGI or PHP rather than Nginx itself.

Typical causes and solutions:

1. PHP memory limit too low – increase memory_limit in php.ini if a script requires large memory.

2. Improper max_children or max_requests in php‑fpm.conf – set children based on available RAM (e.g., 64 children for 1 GB, 128 for 2 GB) and adjust max_requests to a higher value or 0 (unlimited) to avoid frequent process respawns.

3. Header size too small – if Nginx logs show “pstream sent too big header while reading response header from upstream”, increase FastCGI buffers, e.g., fastcgi_buffer_size 32k; .

4. Script execution timeout – tune various timeout directives in Nginx and FastCGI, such as:

fastcgi_connect_timeout 300;
fastcgi_send_timeout 300;
fastcgi_read_timeout 300;
keepalive_timeout 60;

and in php‑fpm.conf:

request_terminate_timeout = 10s

and in php.ini :

max_execution_time = 30

5. Insufficient PHP‑FPM processes – check the number of running php‑fpm workers:

netstat -napo | grep "php-fpm" | wc -l

If the count is near the configured limit, raise the process count (e.g., 100‑200 workers on a 4 GB server).

6. Linux file descriptor limit too low – increase the open file limit for the root user:

echo 'ulimit -HSn 65536' >> /etc/profile
echo 'ulimit -HSn 65536' >> /etc/rc.local
source /etc/profile

7. Small proxy buffers – enlarge Nginx proxy buffers:

proxy_buffer_size 64k;
proxy_buffers 512k;
proxy_busy_buffers_size 128k;

8. Connection reset by peer – may stem from network packet loss or firewall restrictions; ensure proper timeout settings and avoid using request_terminate_timeout to kill PHP processes, preferring request_terminate_timeout=0 for graceful handling.

Sample warning log illustrating a timed‑out script:

May 01 10:50:58.044162 [WARNING] [pool www] child 4074, script '/usr/local/nginx/html/quancha/sameip/detail.php' execution timed out (15.129933 sec), terminating
May 01 10:50:58.045725 [WARNING] [pool www] child 4074 exited on signal 15 SIGTERM after 90.227060 seconds from start
May 01 10:50:58.046818 [NOTICE] [pool www] child 4082 started

By reviewing error logs, adjusting the above configuration parameters, and scaling resources as needed, most 502 errors caused by server overload or misconfiguration can be resolved.