PHP-FPM and Nginx Debugging Guide
Debug PHP-FPM and Nginx integration issues with service status, sockets, pools, logs, permissions and 502 evidence. This Formalint reference is written for working developers, DBAs and support engineers who need a repeatable debugging path instead of a one-line snippet with no context.
Use the notes below as a practical review order: understand the input, capture evidence, make one small change and verify the result before moving to the next assumption.
When to use this page
Find whether the failure belongs to Nginx, PHP-FPM or application code. It is most useful when a small validation or debugging mistake can create noisy tickets, misleading logs or hard-to-review production changes.
Practical workflow
| Step | What to confirm |
|---|---|
| Confirm runtime | Check PHP CLI version and PHP-FPM service version separately. |
| Inspect the socket | Nginx and PHP-FPM must agree on socket path or TCP port. |
| Read both logs | Nginx access/error logs and PHP-FPM logs tell different halves of the story. |
PHP-FPM evidence commands
php -v
systemctl status php-fpm --no-pager
systemctl status nginx --no-pager
ss -lx | grep php
journalctl -u php-fpm -n 100 --no-pagerReview checklist
- Check pool user and file permissions.
- Verify fastcgi_pass matches the active PHP-FPM listener.
- Inspect memory limits and slowlog settings.
- Reload services only after config tests pass.
- Keep deploy rollback notes close to runtime changes.
Common mistake
A 502 may look like an Nginx issue while PHP-FPM is down, overloaded or listening somewhere else.
Formalint is strongest when the page helps the developer decide what the tool cannot prove. Treat every formatter, regex and command as one layer of evidence, not the whole truth.
Frequently asked questions
Is PHP CLI the same as PHP-FPM?
No. They can use different ini files and extensions.
Why does a PHP page download instead of executing?
Nginx may not be passing PHP files to PHP-FPM correctly.
Related Formalint references
Continue with PHP Runtime Guide, Nginx 502 504 Debugging, Nginx Reverse Proxy Checklist.