The Error Scenario
You just deployed a site or updated your server, and suddenly you're staring at a 502 Bad Gateway. When you check the Nginx error logs at /var/log/nginx/error.log, you see a specific complaint:
2023/10/15 10:30:05 [error] 1234#0: *1 connect() to unix:/var/run/php/php8.1-fpm.sock failed (2: No such file or directory) while connecting to upstream...
This message is quite literal. Nginx is trying to hand off a request to PHP-FPM through a Unix socket file, but that file simply isn't there. Without that connection, Nginx cannot process your PHP code.
Why is the Socket Missing?
Three main culprits usually trigger this disconnect:
- The PHP-FPM service is dead: If the service isn't running, it won't create the
.sockfile. - Path Mismatch: Nginx is looking in one folder (like
/var/run/php/), but PHP-FPM is creating the socket elsewhere. - Version Confusion: You recently upgraded from PHP 8.1 to 8.2, but your Nginx config is still hunting for the old 8.1 socket.
How to Fix It
1. Check if PHP-FPM is Running
Start with the most obvious fix. If the service is stopped, the socket file vanishes. Run this command, replacing 8.1 with your specific version:
sudo systemctl status php8.1-fpm
If the output shows inactive (dead) or failed, wake it up:
sudo systemctl start php8.1-fpm
2. Find the Real Socket Path
Don't guess where the socket lives. Instead, ask the PHP-FPM configuration directly. You can find this in the pool configuration file, usually located at /etc/php/[VERSION]/fpm/pool.d/www.conf.
Run this grep command to find the exact path:
grep -E "^listen =" /etc/php/8.1/fpm/pool.d/www.conf
You will likely see something like listen = /run/php/php8.1-fpm.sock. Take note of this exact string. On many systems, /var/run is just a shortcut to /run, but Nginx needs the path to be 100% accurate.
3. Update Your Nginx Config
Now, make sure Nginx is on the same page. Open your site's configuration file, typically found in /etc/nginx/sites-available/.
sudo nano /etc/nginx/sites-available/example.com
Find the location ~ \.php$ block. Ensure the fastcgi_pass line matches the path you found in Step 2:
location ~ \.php$ {
include snippets/fastcgi-php.conf;
# This path MUST match the 'listen' directive in your www.conf
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
}
4. Verify Folder Permissions
Sometimes the file exists, but Nginx is forbidden from touching it. The directory containing the socket (usually /var/run/php/) needs permissions that allow the www-data user to access it. Generally, 755 or 775 permissions are required.
Check the directory ownership:
ls -ld /var/run/php/
If the directory is owned by root and has restricted permissions (like 700), Nginx will fail to connect even if the path is correct.
5. Apply and Test
Configuration changes don't take effect until you reload the services. Always test your Nginx syntax before restarting to avoid crashing your site.
sudo nginx -t
sudo systemctl restart php8.1-fpm
sudo systemctl restart nginx
The Multi-Version Trap
If you have multiple PHP versions installed (e.g., 7.4, 8.1, and 8.3), it is easy to get them mixed up. Run ls -la /var/run/php/ to see every active socket on your system. If you see php8.3-fpm.sock but your Nginx config is pointing to 8.1, you've found your ghost. Update the Nginx config to point to the version that is actually running.
Final Verification
To be absolutely certain the socket is healthy, run:
file /var/run/php/php8.1-fpm.sock
The system should return: socket. If it says "No such file," go back to Step 1. If the file is there, refresh your browser. Your 502 error should be gone, replaced by your live application.