{{img:hero}}When an Nginx reverse proxy breaks, it rarely fails in a “mystery” way. Most outages come from a handful of predictable places: DNS, TLS, upstream reachability, headers, and redirects. This is a workflow playbook you can run even if you’re stuck with just an iPhone and Chrome.

Keep it boring, keep it systematic.

The goal: get from “site is down” to a specific layer you can fix (or hand off) with a clean note.

{{img:layers-map}}

Workflow overview: the 6 checkpoints (run in order)

This order is intentional: each step narrows the failure domain without requiring server access.

  • Checkpoint 1: Confirm what’s failing (which hostname, which path, which protocol)
  • Checkpoint 2: DNS and “wrong place” problems
  • Checkpoint 3: TLS/HTTPS negotiation and certificate mismatches
  • Checkpoint 4: Redirect behavior (301/302 loops, http↔https ping-pong)
  • Checkpoint 5: Upstream health (502/504 vs app errors)
  • Checkpoint 6: Header and body handling (Host, X-Forwarded-*, websockets, upload size)

Checkpoint 1: Pin down the exact symptom (before you “fix” anything)

On iOS, it’s easy to test the wrong thing: a cached redirect, a different hostname, or a path that doesn’t hit the reverse proxy at all.

Do this first:

  • Type the full URL explicitly: https://example.com/ (include the scheme)
  • Try the same host with http:// (yes, even if you expect HTTPS-only)
  • Try a known static path if you have one (for example /health or /robots.txt)
  • Note the first visible error: timeout, connection refused, certificate warning, too many redirects, 502/504, or an app-level error page

Write down what you see in one line (you’ll reuse it in a handoff): URL + status/behavior + time.

Checkpoint 2: DNS and “wrong origin” pitfalls (surprisingly common)

If your reverse proxy is fine but traffic is going to the wrong server, you’ll chase ghosts.

From iPhone + Chrome you can’t run dig, but you can still smoke-test:

  • Switch networks: try cellular vs Wi‑Fi (different resolvers, different caches)
  • Try a second device if possible (or ask someone on a different network to open the same URL)
  • If you use a CDN/WAF, check whether you’re seeing its branded error page vs a plain Nginx error (this hints at where the request dies)

Pitfall: You updated DNS, but some clients still hit the old IP due to TTL or resolver caching. The symptom looks “random”: some people see the new config, some see the old one.

If behavior differs by network, call it out explicitly: “works on cellular, fails on Wi‑Fi” is a strong DNS clue.

Checkpoint 3: HTTPS/TLS failures (cert, SNI, and mixed-host mistakes)

{{img:tls-shield}}

TLS issues often present as “site can’t provide a secure connection” or a certificate name mismatch. Those are not application bugs; they’re edge configuration problems.

  • Hostname mismatch: certificate is for www.example.com but user loads example.com (or the other way around)
  • Wrong certificate served: multiple sites on one IP, but SNI/server_name routing is wrong
  • Old intermediate chain: some clients can’t build the chain (less common now, but still happens)

Pitfall: You test only one hostname (say, the apex), but most users land on the other (www). In Nginx, that’s often a missing server_name entry or a default_server catching traffic.

If you can load http:// but https:// fails immediately, you’re probably not reaching the upstream at all—this is between client and Nginx (or Nginx and certificate files).

Checkpoint 4: Redirect loops and “http↔https ping-pong”

A reverse proxy often rewrites scheme and host. If Nginx and the upstream disagree about whether the request is HTTP or HTTPS, you get loops.

Common loop patterns:

  • Too many redirects after enabling HTTPS
  • Apex redirects to www, and www redirects back to apex
  • Nginx redirects to HTTPS, but upstream thinks it’s HTTP and redirects back (or vice versa)

Pitfall: Missing or incorrect X-Forwarded-Proto (or equivalent) so the app thinks every request is plain HTTP and keeps issuing “upgrade to HTTPS” redirects even though the client is already on HTTPS.

From iPhone, a simple clue is the address bar constantly changing, or a fast loop that ends with a redirect error. Capture the final visible URL and the first URL you typed—those two often reveal the cycle.

Checkpoint 5: 502 vs 504 vs “app error” (what it usually means)

{{img:upstream-pipe}}

These codes help you separate “proxy can’t reach upstream” from “upstream reached but unhappy.”

  • 502 Bad Gateway: Nginx got an invalid response from upstream (crash, wrong port/protocol, upstream speaking TLS when Nginx expects plain HTTP, etc.)
  • 504 Gateway Timeout: Nginx waited but upstream didn’t respond in time (slow app, deadlocked DB, wrong health check path, network ACL)
  • App-level 500/403/404 page: upstream is reachable; now you’re debugging application routing/auth

Pitfall: Pointing proxy_pass at the wrong upstream scheme. Example: upstream listens on HTTPS but Nginx uses http:// (or the reverse). The symptom can look like intermittent 502s or handshake failures.

If you can reach the site sometimes but large pages fail, keep “timeout” and “buffering/body size” issues in mind (next checkpoint).

Checkpoint 6: Header, websocket, and body-size pitfalls (the quiet breakers)

This is where “it loads, but login breaks” or “uploads fail” usually lives.

  • Host header: upstream expects the original host; wrong Host causes wrong virtual host routing
  • X-Forwarded-For: missing means app logs lose real client IPs; rate limiting/auth may misbehave
  • X-Forwarded-Proto: wrong causes bad absolute URLs, secure cookie issues, redirect loops
  • Websockets: missing Upgrade/Connection handling causes chat/stream features to fail
  • Body size: uploads fail with 413 Request Entity Too Large if client_max_body_size is too low

Pitfall: You “fixed” HTTPS at the edge, but cookies are still marked Secure/SameSite in a way that depends on scheme detection. If the app thinks it’s HTTP behind the proxy, sessions can appear to “randomly” drop.

One-page triage note you can send to whoever owns the server

{{img:checklist-card}}

Copy/paste this and fill in the blanks. It saves time and reduces back-and-forth.

  • Time (with timezone): ____
  • URL tested: ____
  • Network: Wi‑Fi (ISP ____) / Cellular (carrier ____)
  • Observed result: timeout / TLS error / too many redirects / 502 / 504 / app error (which?)
  • Does http:// work? yes/no (what happens?)
  • Does https:// work? yes/no (what happens?)
  • Does behavior differ by network? yes/no
  • Any clue about where it fails? CDN/WAF error page vs plain Nginx vs app page
  • Impact scope: all pages or only specific path (e.g., /login, /api, uploads)

Takeaway: treat Nginx failures like a layer-by-layer map

If you walk the checkpoints in order—URL → DNS → TLS → redirects → upstream → headers—you’ll usually land on one specific pitfall instead of “it’s down” as a vague conclusion.

And that makes the actual fix (or the handoff) much faster.