Verify nginx upstreams, sockets, and proxy_pass targets

When to use this guide

Use this guide when nginx returns 502, logs mention upstream failures, or a deploy changed proxy_pass, PHP-FPM sockets, upstream names, ports, containers, or service bindings.

Before you start

Keep a copy of the current server block and upstream config. Do not reload nginx until nginx -t succeeds. If nginx is managed by a hosting panel or container platform, use the platform's reload process.

Step 1: Validate nginx syntax

nginx -t

Expected output is syntax is ok and test is successful. If the test fails, fix the file and line reported before changing services. A syntax failure is usually a config problem, not an upstream health problem.

Step 2: Find the active upstream target

grep -R "proxy_pass\\|fastcgi_pass\\|upstream" /etc/nginx/sites-enabled /etc/nginx/conf.d

Expected output shows whether requests go to a named upstream, a TCP host and port, or a Unix socket. Compare that target with the service you expect to run. Common mistakes are wrong container names, stale ports, missing trailing URI behavior in proxy_pass, and socket paths copied from another PHP version.

Step 3: Check TCP upstreams

ss -ltnp | grep ':3000'
curl -I http://127.0.0.1:3000/

Expected output is a listening process and a response from the upstream. If curl fails locally, nginx cannot proxy to it either. Start or roll back the app service, inspect container port mapping, or correct the upstream host/port.

Step 4: Check Unix sockets and PHP-FPM

ls -l /run/php/
systemctl status php-fpm
systemctl status php8.2-fpm

Expected output is an existing socket readable by the nginx worker user and an active PHP-FPM pool. If nginx logs No such file or directory, the socket path is wrong or PHP-FPM is down. If logs say Permission denied, check socket owner, group, mode, and pool listen settings.

Step 5: Reload safely

nginx -t && systemctl reload nginx

Expected output is a successful syntax test followed by a reload without dropping active connections. If your service manager differs, use its equivalent.

Common misconfigurations

Expected outputs

A healthy TCP upstream has a listening socket in ss output and returns a response to a local curl request. A healthy Unix socket exists at the configured path and is readable by the nginx worker user or group. A healthy nginx config passes nginx -t before reload. When any of those expected outputs is missing, fix that layer before changing timeout values or CDN settings.

If the check is inconclusive

Confirm that you are editing the active virtual host, not a disabled file. Check included config snippets and container-generated files. If a platform writes nginx config from templates, edit the template or control panel setting rather than the generated file, otherwise your fix may disappear on the next deploy.

Verify

Run curl -I against the public URL and the upstream health endpoint. Then watch /var/log/nginx/error.log for recurring upstream lines. A fixed route should stop producing connect() failed, no live upstreams, or timeout messages.

Rollback or escalate

If the reload fails or traffic worsens, restore the previous nginx config and reload after nginx -t. Escalate with the server block, upstream target, service status output, exact nginx log phrase, and the time the first 502 appeared.