{
  "id": "api/http-502-bad-gateway-upstream-timeout",
  "signature": "502 Bad Gateway: Upstream timeout",
  "signature_zh": "502 坏网关：上游超时",
  "regex": "502 Bad Gateway.*upstream timeout",
  "domain": "api",
  "category": "network_error",
  "subcategory": null,
  "root_cause": "The proxy or gateway server (e.g., Nginx, AWS ALB) did not receive a timely response from the upstream server, causing a timeout.",
  "root_cause_type": "generic",
  "root_cause_zh": "代理或网关服务器（例如 Nginx、AWS ALB）未及时收到上游服务器的响应，导致超时。",
  "versions": [
    {
      "version": "Nginx 1.24",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "AWS ALB",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "HAProxy 2.6",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kong 3.4",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Istio 1.18",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "The timeout is on the proxy side, not the client. The proxy's timeout configuration must be adjusted.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The upstream server may be slow due to load or inefficient queries, not a crash.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The upstream server is still under load; immediate retries will likely timeout again.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Increase the proxy timeout value. For Nginx, add 'proxy_read_timeout 120s;' in the location block. For AWS ALB, increase the idle timeout setting in the target group to 120 seconds.",
      "success_rate": 0.85,
      "how": "Increase the proxy timeout value. For Nginx, add 'proxy_read_timeout 120s;' in the location block. For AWS ALB, increase the idle timeout setting in the target group to 120 seconds.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Optimize the upstream server's response time by adding database indexes, caching, or scaling horizontally. Use a CDN or caching layer for static responses.",
      "success_rate": 0.8,
      "how": "Optimize the upstream server's response time by adding database indexes, caching, or scaling horizontally. Use a CDN or caching layer for static responses.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Implement a retry mechanism with exponential backoff. Example in Python: for i in range(3): try: response = requests.get(url, timeout=30); break except requests.exceptions.Timeout: time.sleep(2**i)",
      "success_rate": 0.75,
      "how": "Implement a retry mechanism with exponential backoff. Example in Python: for i in range(3): try: response = requests.get(url, timeout=30); break except requests.exceptions.Timeout: time.sleep(2**i)",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Increase the proxy timeout value. For Nginx, add 'proxy_read_timeout 120s;' in the location block. For AWS ALB, increase the idle timeout setting in the target group to 120 seconds.",
    "Optimize the upstream server's response time by adding database indexes, caching, or scaling horizontally. Use a CDN or caching layer for static responses.",
    "Implement a retry mechanism with exponential backoff. Example in Python: for i in range(3): try: response = requests.get(url, timeout=30); break except requests.exceptions.Timeout: time.sleep(2**i)"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.8,
  "resolvable": "partial",
  "first_seen": "2024-01-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}