tai/runbooks/nginx.md

service, symptoms, tags

service	symptoms	tags
nginx	502 Bad Gateway, 504 Gateway Timeout, upstream connection refused, nginx not starting, failed to bind socket, permission denied reading config, configuration test failed	nginx, web, http, https, proxy, upstream, reverse-proxy, load-balancer

Symptoms

• 502 Bad Gateway — nginx reached the upstream but got an invalid response, or upstream is down
• 504 Gateway Timeout — upstream took too long to respond
• 111: Connection refused in nginx error log — upstream process is not running or not on the expected port
• nginx.service: Start request repeated too quickly — crash-loop; check error log
• [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use) — port conflict
• [emerg] open() ... failed (13: Permission denied) — file permission issue

Diagnostics

Service status

systemctl status nginx

Config test

nginx -t

A config error is the most common reason for nginx failing to start or reload.

Error log

journalctl -u nginx -n 100
tail -n 100 /var/log/nginx/error.log

For 502/504 errors look for: connect() failed, upstream timed out, no live upstreams.

Access log — recent requests

tail -n 50 /var/log/nginx/access.log

Check upstream services

For proxy_pass targets, verify the upstream is running:

systemctl status <upstream-service>
ss -tlnp | grep <upstream-port>

Common upstreams: gunicorn, uwsgi, node, puma, php-fpm.

Port binding conflicts

ss -tlnp | grep ':80\|:443'

Config files

cat /etc/nginx/nginx.conf
ls /etc/nginx/sites-enabled/
cat /etc/nginx/sites-enabled/<vhost>

Check proxy_pass, upstream blocks, proxy_connect_timeout, proxy_read_timeout.

Remediation

Upstream service not running: Start the upstream service, then verify nginx resumes proxying.

Config syntax error: Fix the error shown by nginx -t, then:

systemctl reload nginx

Port already in use: Find the conflicting process with ss -tlnp | grep :80, stop it, then restart nginx.

Upstream timeouts — increase timeouts (caution: treat the slow upstream as the root cause):

proxy_connect_timeout 10s;
proxy_read_timeout 60s;
proxy_send_timeout 60s;

Permission denied on log or socket file:

ls -la /var/log/nginx/
ls -la /run/nginx.pid
chown -R www-data:www-data /var/log/nginx/