Nginx 502 Bad Gateway — Upstream Server Connection and Proxy Errors

Fix Nginx 502 Bad Gateway errors caused by upstream application crashes, socket connection failures, timeout issues, and misconfigured proxy settings. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: 502 Bad Gateway means Nginx received an invalid response from the upstream server it proxied to. The upstream server (PHP-FPM, Node.js, Python, Java) may have crashed, timed out, or refused the connection. Nginx error log (/var/log/nginx/error.log) contains the specific upstream failure reason. Common upstream errors: 'connect() failed', 'upstream prematurely closed connection', 'no live upstreams'. Socket permission issues prevent Nginx from connecting to Unix socket upstreams. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: Upstream application (PHP-FPM, Node.js, Gunicorn) crashed or is not running. Unix socket permissions preventing Nginx worker from connecting to the upstream. Upstream response exceeding Nginx buffer sizes causing invalid response parsing. Upstream application timeout — response takes longer than proxy_read_timeout. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Check Nginx error log: 'tail -50 /var/log/nginx/error.log' — look for upstream connection errors. Verify upstream is running: 'systemctl status php-fpm' or 'systemctl status your-app'. Check socket permissions: 'ls -la /run/php/php-fpm.sock' — Nginx user must have read/write access. Increase buffer and timeout: 'proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_read_timeout 300;'. Test upstream directly: 'curl http://127.0.0.1:3000' to verify the application responds. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our Linux Error Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.