Nginx Bad Gateway: Fix PHP-FPM Socket Errors

An Nginx 502 Bad Gateway error often means Nginx cannot reach PHP-FPM, and a socket error usually points to a missing socket, mismatched path, or permissions problem. These steps help you identify the cause, restore the connection, and verify the site without changing unrelated settings.

What You’ll Need

• SSH access to the server, or access to its hosting control panel.
• Permission to view service status and logs; administrator or sudo access may be needed to edit files or restart services.
• The site’s Nginx configuration and the PHP-FPM pool configuration. Back them up before editing.
• The correct service names for your operating system and installed PHP version. Commands below may need adjustment.

Step-by-Step

1. Confirm the error and check the logs. Reproduce the issue, then inspect Nginx’s error log and the PHP-FPM service log. Common Nginx log locations include /var/log/nginx/error.log; PHP-FPM logs may be in /var/log or available through the system journal. For example, use sudo tail -n 50 /var/log/nginx/error.log and, on a systemd server, sudo journalctl -u php-fpm --since "15 minutes ago". Replace php-fpm with the actual service name. Look for messages such as “No such file or directory,” “Permission denied,” or a connection timeout. These clues determine which steps matter.
2. Check that PHP-FPM is installed and running. Run sudo systemctl status php-fpm, substituting the installed service name if needed. Some systems use a versioned name, such as php8.2-fpm. If the service is stopped, inspect its status output and logs before starting it with sudo systemctl start SERVICE. If it fails to start, fix the reported configuration error first; repeatedly restarting a failing service will not resolve the cause.
3. Find the socket PHP-FPM actually listens on. Open the active PHP-FPM pool configuration, often named www.conf in a version-specific directory. Find the listen setting. A value such as /run/php/php-fpm.sock means PHP-FPM listens on a Unix socket; a value such as 127.0.0.1:9000 means it listens on TCP instead. Check the socket exists with sudo ls -l /run/php/, or confirm the TCP listener with a suitable tool such as ss -ltnp. Paths vary between distributions and PHP versions.
4. Make Nginx’s upstream match. Open the server block for the affected site and locate its PHP location, usually a location ~ \.php$ block. If it uses fastcgi_pass unix:/path/to/socket;, that path must exactly match the pool’s listen path. If the pool listens on TCP, configure the matching address and port, for example fastcgi_pass 127.0.0.1:9000;. Do not switch between socket and TCP unless PHP-FPM is configured to listen on the chosen endpoint. Check that the FastCGI parameters file included by the block exists.
5. Correct socket ownership and permissions if the log says “Permission denied.” The Nginx worker account must be able to access the socket, and its parent directories must allow traversal. In the PHP-FPM pool, review listen.owner, listen.group, and listen.mode. Set the owner or group to an account that gives the Nginx worker access, and use restrictive permissions appropriate to your server—often a group-readable and group-writable socket, rather than world access. Find the worker account in the Nginx configuration or process listing. Avoid chmod 777; it grants unnecessary access and may hide the real issue.
6. Check for stale paths and configuration mistakes. A socket can disappear when PHP-FPM is stopped, or when a configured runtime directory is missing or recreated at boot. Confirm the pool is enabled and its socket directory exists with appropriate ownership. If you edited either configuration, test Nginx before applying it: sudo nginx -t. For PHP-FPM, use its configuration test option if supported, such as php-fpm -t, substituting the correct executable. Resolve every reported syntax error before proceeding.
7. Apply changes and verify the site. Reload Nginx after a successful test with sudo systemctl reload nginx. Restart PHP-FPM only if its configuration changed or it needs recovery: sudo systemctl restart SERVICE. Check both service statuses, reload the affected page, and review fresh logs if the 502 remains. A successful reload does not prove PHP requests work, so test a real application page as well.

Common Mistakes

• Editing a PHP-FPM pool for one version while Nginx is configured for another version’s socket.
• Assuming a socket path from a guide applies to every operating system or package.
• Changing permissions on the socket before checking its owner, group, parent directory, and Nginx worker account.
• Restarting services before checking configuration syntax, which can turn a brief error into a longer outage.
• Testing only a static page. Static files can work even when every PHP request still fails.

Tips

• Keep a copy of each configuration file before editing, and change one setting at a time.
• Use the exact error-log timestamp to match Nginx messages with PHP-FPM events.
• Prefer the server’s package-provided service and configuration paths. Check the service list with systemctl list-units --type=service | grep -i fpm when the service name is unknown.
• If using a hosting panel or container, make changes through its supported configuration mechanism. Generated files may be overwritten when the panel rebuilds configuration.

Troubleshooting

“No such file or directory” for the socket: Compare the Nginx fastcgi_pass path with the PHP-FPM pool’s listen value. Check that PHP-FPM is running and that the socket directory exists. If PHP-FPM logs show it cannot create the socket, investigate the directory path and ownership.

“Permission denied”: Verify the Nginx worker user, socket group and mode, and permissions on every parent directory. If security controls such as SELinux or AppArmor are enabled, check their denial logs and apply the system’s appropriate policy rather than disabling protection wholesale.

Connection refused or timed out: Confirm PHP-FPM is listening at the configured socket or TCP address. For TCP, check the port and whether a firewall or container network rule blocks the connection. A timeout may also mean PHP workers are busy or the application is taking too long; inspect PHP-FPM and application logs before changing timeouts.

The error returns after a reboot: Check whether the runtime socket directory is recreated at startup and whether the service starts in the right order. Use the distribution’s supported runtime-directory or service configuration instead of relying on a manually created socket.

Nginx refuses to reload: Run sudo nginx -t and fix the exact file and line it reports. If the configuration passes but requests still fail, inspect the new error-log entries and confirm the request is reaching the server block you edited.

Frequently Asked Questions

What does “connect() to unix socket failed” mean?
Nginx tried to send a PHP request through a Unix socket but could not connect. The socket may be missing, inaccessible, or different from the path PHP-FPM uses.

Is every 502 error caused by PHP-FPM?
No. A 502 can involve another upstream service or a timeout. Check the Nginx error log to identify which upstream and failure it reports.

Should I use a Unix socket or TCP?
Either can work. Use the endpoint already supported by your PHP-FPM configuration, and make Nginx match it. The best choice depends on the server layout and deployment.

Can I fix the error by setting the socket to 777?
Avoid that. It grants broad access and does not address a wrong path, stopped service, or missing directory. Set access for the actual Nginx worker account instead.

Why does the site work after restarting PHP-FPM but fail again?
A restart may temporarily recreate a missing socket or clear overloaded workers. Check startup logs, runtime-directory handling, worker capacity, and application errors to find the recurring cause.

Can I reload Nginx without restarting it?
Usually, yes: after nginx -t succeeds, a systemd reload applies valid configuration without a full restart. PHP-FPM may need its own reload or restart when its pool settings change.

Related

• Samsung OLED vs QLED vs Neo QLED: Which TV to Buy?
• Best Batch Photo Editors for Mac: What to Choose
• What Happens to Your Code With an AI Coding Assistant?