adminNginx FastCGI PHP-FPM Socket Checklist
Nginx sends PHP requests to PHP-FPM using FastCGI. The connection usually uses a Unix socket or TCP address. If the Nginx fastcgi_pass value does not match the PHP-FPM listen value, PHP pages fail.
Core principle
Nginx and PHP-FPM must agree on the handoff point. Nginx fastcgi_pass points to where PHP-FPM is listening.
Checklist
- Find fastcgi_pass in Nginx config.
- Find listen value in PHP-FPM pool config.
- Compare socket path or TCP address.
- Check whether socket file exists.
- Check socket ownership and permission.
- Check PHP-FPM service status.
- Check Nginx error log for upstream errors.
- Check PHP-FPM config syntax.
- Restart PHP-FPM if socket is missing.
- Reload Nginx after config validation.
Reusable lesson
This applies to 502 errors, PHP version upgrades, WordPress migration, Nginx server block setup and multi-PHP environments.
When to Use This Checklist
Use this checklist when PHP pages return 502, download as files or fail after PHP-FPM version change or Nginx config edits.
Required Tools
SSH access, Nginx config, PHP-FPM pool config, error logs, service status, nginx -t
Before You Start
Do not restart services blindly. First compare Nginx fastcgi_pass with PHP-FPM listen value.
Structured Checklist Steps
- Find fastcgi_pass.
- Find pool listen value.
- Compare handoff target.
- Check socket file.
- Check socket permissions.
- Check PHP-FPM status.
- Read Nginx error log.
- Test PHP-FPM config.
- Restart PHP-FPM if needed.
- Reload Nginx safely.
Verification Steps
- fastcgi_pass matches PHP-FPM listen target.
- Socket exists or TCP listener is active.
- Nginx config test passes.
- PHP-FPM service is active.
- PHP pages load correctly.
Rollback Plan
If a socket change breaks PHP, restore the previous Nginx or PHP-FPM pool config and restart only the affected PHP-FPM version.
Common Mistakes
- Wrong PHP version socket.
- Socket path typo.
- PHP-FPM stopped.
- Permission mismatch.
- Reloading Nginx without testing config.
Related Commands
grep -R "fastcgi_pass" /etc/nginx/sites-enabled/
grep -R "listen =" /etc/php/*/fpm/pool.d/
ls -la /run/php/
sudo systemctl status php8.2-fpm
sudo nginx -t
sudo tail -n 100 /var/log/nginx/error.log