linux troubleshooting guide

Nginx Site Down: A Practical Triage Path

Work from the outside in: DNS answer, TCP listener, Nginx config, service logs, then upstream application behavior.

Problem

The browser says the site is unavailable, users report 502 or 5xx errors, or a deploy changed Nginx behavior. The job is to separate DNS, listener, config, TLS, and upstream failures before restarting random services.

First rule

Do not reload or restart Nginx until you have checked the current listener, config validity, and recent error logs.

Audience

site owners, developers, junior operators, and hosting support learners

Cert context

Useful for service, networking, log, and web-hosting troubleshooting practice. It is cert-adjacent and unofficial.

quick start

Safe first commands

dig +short example.com
curl -I https://example.com/
sudo ss -tulpn | grep ':80\|:443'
sudo nginx -t
journalctl -u nginx --since '30 minutes ago' --no-pager

Separate public DNS from server health

A site can look down because clients resolve the wrong address. Test normal DNS, then force a request to the expected server IP when you need to isolate the web server. If the forced request works and the normal one does not, the outage is probably outside Nginx.

dig +short example.com
curl -I https://example.com/
curl --resolve example.com:443:203.0.113.10 -I https://example.com/

Confirm something is listening on 80 and 443

A running service is not the same as a listening socket. Use `ss` to prove that a process owns the expected ports on the expected address. Bind address matters: listening on `127.0.0.1:443` is not the same as accepting public traffic.

sudo ss -tulpn | grep ':80\|:443'
systemctl status nginx --no-pager

Validate config before reload

Nginx config tests are cheap and prevent a typo from becoming a live outage. Run the test before reloads; if it fails, the output usually names the file and line, which is better evidence than another restart attempt.

sudo nginx -t

Read recent logs by time window

Recent error lines often distinguish syntax errors, permission denials, missing files, TLS issues, upstream connection refusal, and gateway timeout behavior. Keep the time window tight so yesterday's already-fixed error does not become today's false lead.

journalctl -u nginx --since '30 minutes ago' --no-pager
tail -n 80 /var/log/nginx/error.log
grep -iE 'error|failed|denied|timeout|refused' /var/log/nginx/error.log | tail -40

triage logic

How to read the result

forced `curl --resolve` works but normal curl fails

The server may be healthy while DNS, CDN, or resolver cache is wrong.

Next: Investigate DNS records, TTLs, CDN configuration, and authoritative answers.

ports are not listening

Nginx is stopped, failed, bound differently, or another service owns the port.

Next: Check `systemctl status nginx` and recent journal entries before starting anything.

Nginx returns 502 or 504

Nginx may be up while the upstream application is unavailable or slow.

Next: Check upstream service status, sockets, and app logs.

safety notes

Slow down here

Avoid blind restart loops; they erase useful timing and may make an outage worse.
Run `nginx -t` before any reload.
Keep commands read-only until the failing layer is identified.

related commands