Troubleshooting Common Issues
1. Debugging Routing Problems
| Symptom | Likely Cause |
|---|---|
| 404 from gateway | No matching route, path mismatch |
| Wrong upstream | Route priority/order |
| Path stripped/added | strip_path mis-config |
| Host mismatch | SNI/Host header rule |
| Tool | curl -v, gateway debug logs |
2. Resolving Timeout Issues
| Layer | Tune |
|---|---|
| Client → Gateway | request_timeout |
| Gateway → Upstream | upstream_connect/read/send_timeout |
| Upstream → DB | statement_timeout, pool_timeout |
| Idle keep-alive | Server > LB > client |
| 504 from LB | Backend > LB timeout |
3. Troubleshooting SSL/TLS Errors
| Error | Fix |
|---|---|
| CERT_HAS_EXPIRED | Renew certificate |
| UNABLE_TO_VERIFY_LEAF | Install intermediate chain |
| HOSTNAME_MISMATCH | Add SAN, check SNI |
| HANDSHAKE_FAILURE | Cipher/version mismatch |
| Tools | openssl s_client, SSL Labs, testssl.sh |
4. Fixing CORS Configuration
| Symptom | Fix |
|---|---|
| Missing CORS header | Enable plugin, add origin |
| Preflight fails | Allow OPTIONS, Access-Control-Allow-Methods |
| Credentials blocked | Cannot use * + credentials |
| Cache stale | Vary: Origin, lower max-age |
| Wildcard subdomain | Reflect origin from regex |
5. Debugging Authentication Failures
| Error | Cause |
|---|---|
| 401 invalid signature | Wrong JWKS, key rotation |
| 401 token expired | Clock skew, short TTL |
| 401 wrong audience | aud claim mismatch |
| 401 wrong issuer | iss URL mismatch |
| Debug | jwt.io decode, JWKS endpoint check |
6. Resolving Rate Limit Issues
| Symptom | Investigation |
|---|---|
| Unexpected 429 | Check identifier (IP behind NAT?) |
| Limits not enforced | Redis down, fallback to local |
| Counter drift | Clock sync, sync_rate plugin |
| Retry-After ignored | Client doesn't respect header |
| Burst exceeded | Increase capacity vs refill |
7. Troubleshooting Backend Connectivity
| Issue | Diagnosis |
|---|---|
| Connection refused | Backend down, wrong port |
| Connection reset | Backend crash, idle timeout |
| No route to host | NetworkPolicy, security group |
| DNS resolution fail | Resolver, ndots, /etc/resolv.conf |
| TCP reset | SYN-ACK timeout, MTU/MSS |
| Tools | tcpdump, netcat, dig, mtr |
8. Fixing Response Transformation Errors
| Symptom | Cause |
|---|---|
| Invalid JSON returned | Transform breaks structure |
| Empty body | Filter strips required field |
| Content-Length mismatch | Body modified but header not |
| Encoding garbled | Charset, gzip-then-modify |
| Fix | Test transforms in isolation, log before/after |
9. Debugging Cache Invalidation
| Issue | Investigation |
|---|---|
| Stale data after update | Purge fired? Tag mismatch? |
| Cache always misses | Vary header too broad, cookie |
| Wrong response cached | Vary missing, auth header |
| Purge delayed | Multi-PoP propagation lag |
| Tool | X-Cache, Age, surrogate keys |
10. Resolving Load Balancing Issues
| Symptom | Cause & Fix |
|---|---|
| Uneven distribution | Sticky sessions, hash algorithm |
| All traffic to one node | Others failed health check |
| Flapping | Tighten/relax health thresholds |
| Slow node poisoning | Add EWMA, outlier ejection |
| Cold start spikes | Pre-warm, slow start ramp |
| Diagnose | Per-upstream metrics, access logs by node |