Troubleshooting PHP-FPM 502 Bad Gateway Errors

Nginx 502 can indicate inaccessible FPM sockets, failed workers or invalid FastCGI routing.

What It Does and When to Use It

Set parameters in the FPM pool configuration; avoid exposing pool status publicly. The web server handles HTTP, the PHP worker executes scripts, and CLI has separate configuration and lifecycle.

Requirements, Inputs and Expected Behavior

Confirm the runtime, extension, environment variables, and permissions before running the examples in production. Check both Nginx and FPM logs before increasing timeouts.

Example 1: Basic Operation

Set parameters in the FPM pool configuration; avoid exposing pool status publicly.

listen = /run/php/app.sock
pm = dynamic
pm.max_children = 8

Example 2: Behavior and Validation

Run the matching status or validation command on the intended host.

sudo ss -xl | grep php

Practical Example: Application Use

Correlate capacity, worker crashes and slow requests using logs and process state.

sudo systemctl status php8.4-fpm --no-pager
sudo journalctl -u php8.4-fpm -n 35 --no-pager

Important Behavior and Edge Cases

The second example highlights: Run the matching status or validation command on the intended host. The practical example adds: Correlate capacity, worker crashes and slow requests using logs and process state.

Comparison with Related Approaches

Approach	What changes
Web server, worker and PHP CLI	The web server handles HTTP, the PHP worker executes scripts, and CLI has separate configuration and lifecycle.
Choosing safely	Check the effective configuration in the SAPI serving requests before changing production.

Common Beginner Mistakes

Mistake	Correct approach
Checking the PHP CLI INI instead of FPM	Inspect phpinfo or configuration through the protected web SAPI.
Exposing worker status publicly	Restrict FPM diagnostics to localhost or a monitored private network.
Skipping operational constraints	Check both Nginx and FPM logs before increasing timeouts.

Key Takeaways

Nginx 502 can indicate inaccessible FPM sockets, failed workers or invalid FastCGI routing.
Correlate capacity, worker crashes and slow requests using logs and process state.
Check the effective configuration in the SAPI serving requests before changing production.