Nginx 502 Bad Gateway: causes and how to fix it

Each cause of a 502 writes a different message, so the log tells you which of the fixes below applies.

1. Follow the error log and reload the failing page (the default path on most Linux packages is shown; check the error_log directive if yours differs):
   Terminalneeds sudo / rootCopy

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

2. Match the message: Connection refused → fix 2; No such file or directory with a socket path → fix 3; Permission denied → fix 4; too big header → fix 5; prematurely closed → fix 2 and the app's own log; upstream timed out → it is really a 504, see the note in fix 5.

Connection refused means nothing accepts connections on the address Nginx uses. The app must be started, or restarted after a crash.

1. Check the service (replace the name with your app's systemd unit, for example php8.3-fpm, gunicorn or myapp):
   TerminalCopy

   systemctl status myapp
   journalctl -u myapp -n 50 --no-pager

2. See what is actually listening on the port from your proxy_pass line (here 3000):
   Terminalneeds sudo / rootCopy

   sudo ss -ltnp | grep 3000

3. Ask the app directly, bypassing Nginx. A normal HTTP answer means the app is fine and the problem is in the Nginx configuration:
   TerminalCopy

   curl -i http://127.0.0.1:3000/

4. If the app is stopped or crashing, start it and read its own log for the reason (missing environment variable, port already in use, out of memory). For containers, docker ps and docker logs <container> show the same.

Nginx and the app have to agree on one address. A typo, a changed port, or a renamed socket after an upgrade breaks every request.

1. Find where Nginx sends requests:
   Terminalneeds sudo / rootCopy

   sudo nginx -T | grep -nE 'proxy_pass|fastcgi_pass|upstream'

2. Compare it with the app's listen address. For PHP-FPM, the socket path is the listen line of the pool file:
   TerminalCopy

   grep -R '^listen' /etc/php/*/fpm/pool.d/
   ls -l /run/php/

3. Correct the proxy_pass (or fastcgi_pass) line, for example:
   nginx.confCopy

   location / {
       proxy_pass http://127.0.0.1:3000;
   }
   
   location ~ \.php$ {
       include fastcgi_params;
       fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
       fastcgi_pass unix:/run/php/php8.3-fpm.sock;
   }

4. Test and reload:
   Terminalneeds sudo / rootCopy

   sudo nginx -t && sudo systemctl reload nginx

With (13: Permission denied) the address is right but the Nginx worker user (often www-data or nginx) may not open the socket, or SELinux forbids Nginx from making network connections.

1. Check which user Nginx runs as and who owns the socket:
   TerminalCopy

   ps -o user= -C nginx | sort -u
   ls -l /run/php/php8.3-fpm.sock

2. For PHP-FPM, set the socket owner in the pool file to the Nginx user, then restart PHP-FPM:
   ConfigCopy

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

3. On RHEL, Rocky, Alma or Fedora with SELinux enforcing, a proxy to a TCP port is blocked by default. Check for denials and allow Nginx to connect:
   Terminalneeds sudo / rootCopy

   sudo ausearch -m avc -ts recent | grep nginx
   sudo setsebool -P httpd_can_network_connect 1

Nginx reads the start of the upstream response, including headers, into a buffer of one memory page (4K or 8K) by default. Large cookies or many headers overflow it and Nginx answers 502 with upstream sent too big header.

1. Add larger buffers in the location or server block that proxies the app:
   nginx.confCopy

   proxy_buffer_size 16k;
   proxy_buffers 8 16k;
   proxy_busy_buffers_size 32k;

2. For PHP-FPM use the matching fastcgi_buffer_size and fastcgi_buffers directives instead.
3. Test with sudo nginx -t and reload. If the log instead says upstream timed out, the request is too slow rather than broken: raise proxy_read_timeout (default 60s) only after making the slow request faster where possible.