Topic cluster
Troubleshooting proxies
Read 502, 503 and 504 correctly, drive curl through a proxy, understand no_proxy, survive a corporate proxy, and bisect a chain methodically.
Most proxy debugging goes wrong in the first minute, because the investigation starts at the layer that reported the error rather than the layer that caused it. A proxy reports what it experienced, which is usually a symptom of something one hop further in.
The method that works is always the same: draw the chain, bisect it, and find the innermost hop that still shows the fault. A proxy debugging playbook is the long form of that method, and everything else in this cluster is a specific case of it.
By symptom#
| Symptom | Start here |
|---|---|
| 502, 503 or 504 | 502 vs 503 vs 504 |
| Intermittent 502 under load | Keep-alive and upstream connection pooling |
| 504 with no upstream log line | Timeout budgets |
upstream sent too big header | Header and body size limits |
| Wrong client IP in the logs | Configuring trusted proxies |
| Infinite redirect loop over HTTPS | X-Real-IP, X-Forwarded-Proto, Host and Port |
| 404 only for one path prefix | nginx proxy_pass and the trailing slash |
| Some tools bypass the proxy, others do not | The no_proxy environment variable |
unable to get local issuer certificate | TLS interception and corporate root CAs |
| npm, pip, git or docker failing at work | Corporate proxies and developer tooling |
The one tool to learn properly#
curl through a proxy is worth reading even if you already use curl daily. The --write-out timing breakdown alone will localise most latency problems to a single hop in one command.
Every guide in this cluster#
- 502 vs 503 vs 504: reading proxy errors correctlyWhat the proxy actually experienced behind 502, 503 and 504, with nginx error_log strings, HAProxy termination flags and Envoy response flags decoded.
- Corporate proxies and developer toolingHow to point curl, git, npm, pip, Java, Go, Docker, apt, Maven and VS Code at a corporate proxy and its root CA, with the gotcha for each tool.
- curl through a proxyEvery curl proxy flag that matters, how to read -v output by phase, and a --write-out timing string that shows whether the proxy or the origin is slow.
- Header and body size limits at the proxyWhy requests die at the proxy before the app sees them: nginx buffer directives, 400/413/431/494/502, the upstream-sent-too-big-header fix, and a defaults table.
- The no_proxy environment variableHow curl, Go, Python requests, urllib, wget and Java each interpret no_proxy, the portable subset that works everywhere, and the suffix-matching trap.
- A proxy debugging playbookA repeatable method for proxy faults: draw the topology, bisect the chain, correlate with a request ID, read timers in order, reproduce, then capture packets.