nginx 502 Bad Gateway: fixing "connect() failed" to PHP-FPM and other upstreams

nginx logs connect() failed (111), (2) or (13) when it can't reach your app. What each errno means, and how to fix PHP-FPM sockets, ports, permissions and SELinux.

· 7 min read · By the Spot Downtime team

When nginx returns 502 Bad Gateway, the browser page tells you nothing. The useful part is in nginx's error log, where a line like connect() failed (111: Connection refused) while connecting to upstream says exactly why. This post decodes the common variants and how to fix each one.

If your log says upstream timed out instead, the upstream was reachable but slow. That is a different problem, covered in nginx upstream timed out.

Start with the error log

On most Linux systems the log is at /var/log/nginx/error.log. Look at the lines from the time of the 502:

bash
sudo tail -n 50 /var/log/nginx/error.log
# or, if nginx logs to journald
sudo journalctl -u nginx --since "10 minutes ago"

Each line ends with the upstream: address nginx tried, such as fastcgi://unix:/run/php/php8.2-fpm.sock or http://127.0.0.1:3000. That tells you which backend to inspect. The number in brackets after "failed" is the operating system's errno:

  • (111: Connection refused): nothing is listening at that address.
  • (2: No such file or directory): the Unix socket file doesn't exist.
  • (13: Permission denied): the socket exists but nginx isn't allowed to use it.
  • (11: Resource temporarily unavailable): the socket's connection queue is full.
  • (110: Connection timed out): packets to the address are being dropped, usually a firewall or wrong host.

111 Connection refused: the backend isn't running or isn't listening there

This is the most common one. The process crashed, never started after a reboot or deploy, or listens on a different port than nginx expects. Check that something is listening:

bash
sudo ss -ltnp | grep -E ':3000|:9000'
systemctl status php8.2-fpm        # or your app's service name
sudo journalctl -u php8.2-fpm -n 50

If the service is down, the service log usually shows the crash reason: a config error, an out-of-memory kill (see Linux out of memory) or a port already in use. Restart it and watch the 502s stop.

The localhost versus IPv6 trap

If the log shows connect() failed (111) to [::1]:3000 while your app is running, the app is bound to IPv4 only and nginx resolved localhost to the IPv6 address. Use the explicit IPv4 address in the config:

nginx
location / {
    proxy_pass http://127.0.0.1:3000;   # not http://localhost:3000
}

2 No such file or directory: wrong socket path

A PHP upgrade is the classic trigger. nginx points at php8.1-fpm.sock but the installed version now creates php8.2-fpm.sock. Compare what nginx wants with what exists:

bash
grep -rn fastcgi_pass /etc/nginx/
ls -l /run/php/

Then make the two agree, either by changing fastcgi_pass or the pool's listen setting:

nginx
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

Test and reload with sudo nginx -t && sudo systemctl reload nginx.

13 Permission denied: nginx can't open the socket

A Unix socket is a file with an owner and permissions. The nginx worker runs as a user such as www-data (Debian and Ubuntu) or nginx (RHEL family), and that user must be allowed to write to the socket. In the PHP-FPM pool file, for example /etc/php/8.2/fpm/pool.d/www.conf:

ini
listen = /run/php/php8.2-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

Restart PHP-FPM afterwards. Also check that the user in nginx's user directive matches the owner or group above.

On RHEL, CentOS, Rocky or Fedora, check SELinux

With SELinux enforcing, nginx can be denied even when file permissions are right. To let nginx proxy to a TCP backend, run sudo setsebool -P httpd_can_network_connect 1. Denials are logged in /var/log/audit/audit.log; search it with sudo ausearch -m avc -ts recent.

11 Resource temporarily unavailable: the backend is saturated

This appears under load. PHP-FPM is running, but every worker is busy and the socket's backlog is full, so new connections are refused immediately. Confirm in the PHP-FPM log:

text
WARNING: [pool www] server reached pm.max_children setting (5), consider raising it

Raising pm.max_children helps only if the server has the memory for more workers. Estimate memory per worker with ps --no-headers -o rss -C php-fpm8.2 and divide the RAM you can spare by that number. If requests are slow because of a database or an external API, more workers just move the pile-up; find the slow part instead. The listen.backlog setting and the kernel's net.core.somaxconn control how many connections can queue.

110 Connection timed out: the network path is broken

When the upstream is a separate server or container, a timeout while connecting means packets aren't arriving. Check that the IP is current (containers get new addresses after a redeploy), that a security group or firewall allows the port, and test from the nginx host with curl -v http://10.0.0.5:3000/.

In Docker, use the service name on a shared network rather than a hard-coded IP. nginx also resolves hostnames in proxy_pass only once at startup, so a backend that moved to a new IP needs nginx -s reload.

A quick decision path

  1. Read the last connect() failed line and note the errno and the upstream address.
  2. Check the backend: is the service running, and does ss -ltnp show the expected port or socket?
  3. Check that the nginx config and the backend config name the same address.
  4. Check permissions, then SELinux, for sockets.
  5. If the failures only come under load, look at worker limits and slow dependencies.

Know about the 502 before visitors tell you

A backend that dies at 3 a.m. makes nginx answer 502 on every request while nginx itself looks healthy, so a check that only pings the server will not notice. A website monitor that requests a real page and expects a 200 will, and an API monitor can assert on a health endpoint that touches the database. Spot Downtime confirms failures from three regions before it alerts, so you hear about a real outage rather than one dropped request.

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading