Encountering a 502 error after domain resolution? Troubleshooting server configuration issues.

　　The domain name resolves correctly to the server's IP address—verified via `nslookup` or `dig`—yet opening the site in a browser results in a "502 Bad Gateway" error. This scenario is actually more subtle than a simple DNS resolution failure; it indicates that the request successfully reached the server, but an issue occurred while the server was processing it.

　　At its core, a 502 error means the gateway failed to receive a valid response from the upstream service. In a typical LNMP architecture, Nginx acts as the gateway, while PHP-FPM (or a backend like Node.js or Tomcat) serves as the upstream component. A 502 error occurs whenever communication between the two is interrupted. This article breaks down the troubleshooting process into four key areas: service status, configuration matching, resource limits, and security policies.

　　First, determine exactly which layer the request reached.

　　Before diving into server diagnostics, use a simple method to narrow down the scope of the problem.

　　Run the following command in your local terminal:

curl -I http://example.com

　　Check the returned status code. A 502 error indicates that the request reached Nginx and Nginx attempted to forward it to the backend, but the backend failed to provide a valid response. If the error is "connection timed out" or "connection refused," the issue lies at a lower level—such as the port not listening, a firewall blocking the connection, or a security group not allowing the traffic.

　　After confirming the 502 error, log in to the server and start by checking the Nginx error log:

tail -f /var/log/nginx/error.log

　　Logs often provide direct clues. Here are a few common ones:

　　connect() failed (111: Connection refused)：The upstream service has not started, or the listening address/port is incorrect.

　　connect() to unix:/run/php/php8.1-fpm.sock failed (2: No such file or directory)：The socket path configured in Nginx does not match the path actually being listened on by PHP-FPM.

　　upstream timed out (110: Connection timed out)：The backend response was too slow and timed out.

　　Troubleshooting should follow the direction indicated by the logs; checking everything item by item from scratch is necessary only when logs are unavailable.

　　Level 1: Check if PHP-FPM (or the backend service) is running.

　　This is—without a doubt—the most common cause of a 502 error. Nginx does not process PHP itself; it forwards `.php` requests to PHP-FPM. If PHP-FPM has crashed or failed to start, Nginx naturally cannot receive a response.

systemctl status php-fpm

　　If it shows "inactive (dead)" or "failed," start it directly:

systemctl start php-fpm
systemctl enable php-fpm

　　Pay attention to the version number. On Ubuntu, the service name for PHP 8.1 is typically `php8.1-fpm`, rather than the generic `php-fpm`. Use `systemctl list-units | grep php` to verify the actual service name.

　　If the service starts but immediately crashes, check the detailed error:

journalctl -u php8.1-fpm -n 50 --no-pager

　　Common causes include syntax errors in configuration files, extension conflicts, or occupied ports.

　　Step 2: Verify that the communication method between Nginx and PHP-FPM matches.

　　If PHP-FPM is running but Nginx still cannot connect, it implies a mismatch in their communication settings.

　　PHP-FPM supports two listening methods: Unix sockets and TCP ports. The Nginx `fastcgi_pass` directive must exactly match the PHP-FPM `listen` configuration.

　　First, check what PHP-FPM is listening on:

grep listen /etc/php/8.1/fpm/pool.d/www.conf

　　There are two possible outcomes:

　　listen = /run/php/php8.1-fpm.sock(Unix Socket)

　　listen = 127.0.0.1:9000(TCP port)

　　Let's take another look at what is written in the Nginx configuration:

grep fastcgi_pass /etc/nginx/sites-enabled/Your site configuration file

　　If the Nginx configuration specifies `fastcgi_pass 127.0.0.1:9000;` but PHP-FPM is actually listening on a socket file, there is a mismatch, and a 502 error is inevitable. Simply aligning the two configurations will resolve the issue.

　　If using socket mode, you also need to check permissions. The Nginx worker process (usually the `www-data` user) must have permission to access the socket file:

ls -l /run/php/php8.1-fpm.sock

　　The correct permissions should be `srw-rw---- www-data www-data`. If the owner is not `www-data` or the permissions are incorrect, configure this in the PHP-FPM `www.conf` file:

listen.owner = www-data
listen.group = www-data
listen.mode = 0660

　　Then, restart PHP-FPM.

　　Level 3: Check for resource exhaustion

　　If the service status is normal and the configuration is correct, yet you encounter 502 errors as soon as traffic spikes—or experience intermittent glitches—the issue may lie at the resource level.

　　A common scenario is the PHP-FPM process pool becoming fully saturated. The `pm.max_children` setting in PHP-FPM limits the number of processes that can handle requests simultaneously. When all child processes are busy and new requests are queued, Nginx returns a 502 error after a timeout.

　　Check current process usage:

ps aux | grep php-fpm | wc -l

　　Compare the `pm.max_children` value in `www.conf`. If the actual number of processes is already close to or equal to the limit, you need to increase it. However, keep in mind that each PHP process consumes approximately 20–30 MB of memory; check if your server has sufficient memory before increasing the value.

free -h

　　If memory is plentiful, increase the setting in www.conf:

pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 10

　　Restart PHP-FPM after making adjustments.

　　Another resource-related pitfall is disk space. If the root partition is full, PHP-FPM cannot write session files, logs, or temporary files, which can trigger a 502 error. Check this using `df -h`.

　　Layer 4: Are security policies causing issues?

　　If configurations and resources are fine but the 502 error persists, the problem might lie with security modules.

　　SELinux (on CentOS/RHEL systems) is a classic culprit. By default, it blocks Apache or Nginx from initiating connections to network backends. If SELinux is enabled, Nginx will fail to connect to PHP-FPM even if the configuration is perfectly correct.

　　Method for temporary verification:

setenforce 0

　　If the 502 error disappears immediately, it indicates an SELinux issue. The permanent solution is to allow network connection permissions for httpd:

setsebool -P httpd_can_network_connect 1

　　AppArmor (on Ubuntu) can exhibit similar behavior, though it is relatively rare. If you suspect this is the cause, run `dmesg | grep apparmor` to check for denial logs.

　　If using a CDN or reverse proxy

　　A 502 error does not necessarily occur at the "Nginx → PHP-FPM" stage. If your website sits behind a CDN, or if the server itself acts as a reverse proxy for another service, the 502 error might originate in the origin-pull connection.

　　A common cause is the origin server's firewall blocking the CDN's origin-pull IP addresses. CDN origin-pull node IP ranges change dynamically as nodes are added; if the origin server's security group whitelist isn't updated promptly, requests from new nodes will be blocked, resulting in a 502 error for the client.

　　Troubleshooting method: Locate the list of origin-pull IPs in the CDN console and verify that these IP ranges are allowed in the origin server's security group. Also, check if the Nginx `proxy_read_timeout` is shorter than the CDN's configured origin-pull timeout to avoid misdiagnosis caused by a timeout mismatch.

　　Summary of troubleshooting workflow

　　When encountering a "502 error despite successful DNS resolution," follow this sequence:

　　Step 1: Check Nginx error logs and use keywords to identify the issue. "Connection refused" indicates the service isn't running; "No such file" indicates a socket path mismatch; "timed out" points to performance or timeout issues.

　　Step 2: Check the backend service status. Run `systemctl status php-fpm`; start it if it isn't running, or check the journal logs if startup fails.

　　Step 3: Verify the communication configuration between Nginx and PHP-FPM. The `fastcgi_pass` and `listen` directives must match; if using socket mode, also check file permissions.

　　Step 4: Check resources. Determine if the PHP-FPM process pool is saturated, memory is exhausted, or the disk is full.

　　Step 5: Check security policies. On CentOS, disable SELinux temporarily to test if the request is being blocked. Step 6: If a CDN is in use, check the origin-pull IP whitelist and timeout configurations.

　　Most 502 errors can be diagnosed within the first three steps. The key is not to blindly restart services, but to examine the logs first and let them reveal which layer the problem lies in.