502 Bad Gateway: Diagnose PHP-FPM and Reverse Proxy Failures

Your WordPress site shows 502 Bad Gateway in the browser, but the DNS records appear correct. Instead of changing DNS records at random, separate the request path into its individual layers. The visitor first uses DNS to find an IP address. The reverse proxy then accepts the request and passes PHP work to PHP-FPM. In many cases, the failure occurs during this second step.

This guide explains how to diagnose a 502 Bad Gateway PHP-FPM error through socket access, TCP upstreams, PHP-FPM pool capacity, timeouts and proxy configuration. The goal is to identify the narrowest likely cause, apply one targeted correction and verify the result.

Separate DNS from PHP-FPM in a 502 error

DNS determines which IP address answers for your domain. PHP-FPM is the FastCGI process manager that the web server uses to execute PHP code. DNS can point to the correct server while the proxy on that server cannot reach PHP-FPM.

Start by sending the same request through the public hostname and, if possible, directly to the local web server. These commands only observe the response. Replace the example domain, port and Host header with values from your environment. The examples assume a Unix-like system with curl and dig installed.

curl -I https://your-domain.example/

Record the response code, date and time. If you can test the local web server with the correct virtual-host header, use an approach such as:

curl -I -H 'Host: your-domain.example' http://127.0.0.1/

If both requests reach the same local proxy, this test does not prove that DNS is correct by itself. It only shows that the local proxy can be reached. Check the DNS result and then search the proxy access and error logs for the same time window.

dig +short your-domain.example

If the domain resolves to an unexpected IP, correct the DNS or caching issue first. If it resolves to the expected server and the proxy log contains an upstream connection error, changing DNS will not repair the PHP-FPM connection.

Use logs to identify the actual 502 cause

A proxy can return 502 when it cannot connect to an upstream or cannot obtain a valid HTTP or FastCGI response. The wording in the log determines which correction to investigate. Connection refused, No such file or directory, Permission denied and upstream timed out describe different failures.

What common proxy messages mean

• Connection refused: Nothing is listening on the TCP port, or the service is not accepting connections.
• No such file or directory: The Unix socket path in the proxy configuration does not exist. PHP-FPM may be stopped, using another socket or configured with a different path.
• Permission denied: The socket exists, but the web-server user cannot access the file or one of its parent directories.
• Upstream timed out: PHP-FPM did not produce a response before the proxy timeout. A busy pool, slow query, locked plugin or long PHP operation may be involved.
• Invalid response: The upstream response is incomplete, malformed or not compatible with the protocol the proxy expects.

Log paths vary by distribution, control panel and virtual-host configuration. Do not assume a path. Check the active virtual-host configuration for its error-log directive or use the log section in your hosting panel. On a VPS where you can manage services with systemd, general status and recent records may be available with:

sudo systemctl status php8.2-fpm --no-pager
sudo journalctl -u php8.2-fpm --since "15 minutes ago" --no-pager

php8.2-fpm is only an example. Your service may be named php8.1-fpm, php8.3-fpm or something different. Determine the active PHP-FPM version and service name before running service commands.

Also check the WordPress application log for PHP errors. A plugin fatal error more often produces a 500 response or a blank page than a direct 502, but it can still contribute to worker crashes or unusually long requests. Time correlation matters. The PHP error logging best practices guide can help you separate application errors from proxy failures.

Fix a PHP-FPM Unix socket connection

With a Unix socket, the proxy and PHP-FPM communicate through a file on the same server. The socket path created by PHP-FPM must exactly match the path used by the proxy in fastcgi_pass or an equivalent upstream directive.

Check whether the socket exists

First locate the socket path in the active proxy configuration. Then inspect that exact path:

sudo ls -l /run/php/php8.2-fpm.sock
sudo stat /run/php/php8.2-fpm.sock

If the file is missing, distinguish between two possibilities: PHP-FPM is not running, or PHP-FPM is creating a different socket. Check the active pool configuration:

sudo grep -R "^[[:space:]]*listen[[:space:]]=" /etc/php/8.2/fpm/pool.d/

Directories differ by distribution and PHP version. If the proxy path and the pool’s listen value do not match, determine which configuration is active and correct only the wrong reference. Do not change the socket paths for every pool at once.

Check socket ownership and directory access

When the socket exists but the log says Permission denied, inspect its owner, group and mode:

sudo ls -l /run/php/php8.2-fpm.sock
namei -l /run/php/php8.2-fpm.sock

The user running the web-server worker must be able to access the socket and each required parent directory. Compare that user with the pool’s listen.owner, listen.group and listen.mode settings. These values are commonly defined in the pool configuration.

Back up the relevant pool file before changing permissions:

sudo cp /etc/php/8.2/fpm/pool.d/www.conf /etc/php/8.2/fpm/pool.d/www.conf.bak

Change only the owner, group or mode value needed for the proxy user to connect. Making the socket writable by everyone may hide the error, but it grants broader access than necessary. A group-based permission model is usually a narrower correction.

Test the configuration using the command supported by your installation, then reload or restart only the affected service:

sudo php-fpm8.2 -t
sudo systemctl reload php8.2-fpm

The binary name, test option and reload behavior can differ. If reload is not supported or does not recreate the socket, use the service’s documented safe restart method. Afterward, confirm that the socket was recreated with the expected ownership and mode. Request the affected URL again and check that the proxy no longer reports a socket error.

Check a TCP upstream and PHP-FPM port

Some installations use a TCP address such as 127.0.0.1:9000 instead of a Unix socket. Socket existence and file permissions are irrelevant in that design. Check whether PHP-FPM is listening on the address and port configured in the proxy.

sudo ss -ltnp | grep ':9000'

If there is no output, PHP-FPM may not be listening on that port. Compare the pool’s listen setting with the service state:

sudo grep -R "^[[:space:]]*listen[[:space:]]=" /etc/php/8.2/fpm/pool.d/
sudo systemctl status php8.2-fpm --no-pager

If the proxy connects to 127.0.0.1:9000 while PHP-FPM listens on another port or only on a Unix socket, the endpoints do not match. Preserve the existing architecture and correct only the wrong upstream address when possible. Do not switch from a socket to TCP simply because the first check was inconclusive.

Remember that PHP-FPM is not an HTTP server. Sending an HTTP request with curl to its FastCGI port is not a meaningful application test. Use the listening state, proxy logs and PHP-FPM logs together. A missing port at the time of a connection-refused error points toward the service or listen setting; an active port requires investigation of the address, network policy or pool capacity.

Investigate a full PHP-FPM pool

A PHP-FPM pool is a group of worker processes that execute PHP requests. The pm.max_children setting limits how many workers can run at the same time. If all workers are occupied by long requests, new requests wait. When the proxy’s wait period expires, the result may be a 502 or, in some configurations, a 504.

PHP-FPM can therefore appear active while the pool is at capacity. Warnings such as server reached pm.max_children are significant when they coincide with timeout entries in the proxy log.

First identify which requests are taking time. Heavy WordPress plugins, external API calls, slow database queries and large administrative operations can all keep workers busy. Keep PHP-FPM web workers separate from CLI cron or queue workers: a CLI job that does not make an HTTP request does not consume an FPM worker. It can still delay web requests by locking the same database or files.

Do not raise pm.max_children at random. Each additional worker can consume memory. Check RAM usage, process counts, request duration and PHP-FPM warnings before changing pool capacity. The guide to PHP-FPM settings for WordPress and WooCommerce explains how to assess pm.max_children and pm.max_requests within the available resources.

If one plugin or request is responsible, create a backup and a rollback plan before making a production change. For a data-changing WordPress operation, confirm that both the database and site files can be restored. A lower-risk first step is to identify the slow request and its PHP error, then apply or test the plugin or query correction in a controlled environment.

Distinguish timeouts, proxy settings and app errors

A proxy that cannot connect to PHP-FPM is different from one that connects but receives no response in time. Connection refused points to the connection phase; timed out usually points to response time or resource pressure.

If PHP-FPM accepts the request but WordPress takes too long, increasing the proxy timeout may only delay the visible failure. First inspect the PHP-FPM slow log, application log and database slow-query records for the same request. If the operation is legitimately long, a carefully justified timeout change may be appropriate. Very high timeouts can keep workers occupied for longer and make pool exhaustion worse.

Missing FastCGI parameters are not usually the main cause of a 502, but an incorrect SCRIPT_FILENAME, document root or PHP version can produce other failures. Confirm that the virtual host points to the intended PHP-FPM pool and is not using another site’s socket.

Test the active proxy configuration before reloading it. On an Nginx VPS with the Nginx command available, for example:

sudo nginx -t

If the test fails, do not reload. Fix the file and line identified by the test. After a successful test, perform a controlled reload and call the same URL again. If the 502 remains, restore the previous configuration and test a separate hypothesis instead of accumulating unrelated changes.

Use status and ping endpoints safely

PHP-FPM status or ping settings can provide additional information about pool health. Enabling the feature and exposing a safe web-server route are separate tasks.

First check whether the pool configuration supports and enables the status or ping setting. Do not expose such an endpoint directly to the public internet. In Nginx or Apache, restrict access to local administration, a VPN or another authenticated management path. Operational details such as process counts and request states may be visible there.

This endpoint is not required for every 502 diagnosis. Proxy and PHP-FPM logs, service status and socket or port checks resolve many cases. If you enable monitoring, back up the pool file, test the configuration and separately verify the web-server rule that blocks unintended external access.

WordPress and WooCommerce-specific symptoms

If the homepage works but the WordPress dashboard, product search or checkout returns 502, the failure may affect only heavier requests. These paths can generate complex queries, external service calls or longer cart operations. Establish whether every URL fails or only one feature does.

For WooCommerce, delays in stock, shipping, payment or tax services can leave an FPM worker waiting. That is not automatically a DNS problem. Review external-service access, application timeouts and pool usage together. Before removing a plugin, take a backup, identify the slow call in the logs and test the change in staging when possible.

Clearing caches does not repair a persistent upstream failure. First prove that the proxy can reach PHP-FPM. If a cache layer is serving an old 502 response, inspect its configuration separately, but do not repeatedly clear caches without confirming the live source of the error.

Frequently Asked Questions

Can a firewall cause a PHP-FPM 502?

Yes, when PHP-FPM is reached through TCP and a network policy blocks the configured address or port. Confirm the listening socket and policy before changing firewall rules. A local Unix socket does not pass through the network firewall in the same way.

Should you restart PHP-FPM whenever you see 502?

Not automatically. A restart may clear a temporary stuck process but will not fix a wrong socket path, permission problem or incorrect upstream. Read the matching log entry first, and use a controlled restart only when the service state or a documented configuration change requires it.

Does a browser refresh prove that the fix worked?

No. Test the same URL after the change, then confirm the proxy and PHP-FPM logs show a successful request or at least no new matching error. Also test the affected WordPress or WooCommerce action if the failure was limited to one feature.

When should you contact the hosting provider?

Contact the provider when you cannot access service logs or pool settings, or when the provider controls the reverse proxy, PHP-FPM service or resource limits. Include the URL, exact time, status code and relevant log message.

Short checklist for diagnosing 502

1. Record when the failure started and which URLs are affected.
2. Confirm that the domain resolves to the expected IP address.
3. Classify the proxy error as connection refused, missing socket, permission denied or timeout.
4. Verify the correct PHP-FPM service name and active status.
5. For Unix sockets, compare the path, owner, group and parent-directory permissions.
6. For TCP upstreams, confirm that the expected address and port are listening.
7. Look for pool-limit, worker-crash and slow-request warnings in the FPM log.
8. Back up configuration before a change, modify the narrowest setting and keep the rollback path.
9. After a configuration test, request the same URL and compare the proxy and PHP-FPM logs.

If the 502 continues, roll back the last change and compare one request across the proxy, PHP-FPM and application logs using the same timestamp. That gives you a clear next step without mixing DNS, proxy, PHP-FPM and WordPress symptoms together.