{
  "id": "nginx/proxy-buffer-size-too-small",
  "signature": "upstream sent too big header while reading response header from upstream, client: 10.0.0.1, server: example.com, upstream: \"http://127.0.0.1:8080\"",
  "signature_zh": "上游发送的标头过大，同时从上游读取响应标头，客户端：10.0.0.1，服务器：example.com，上游：“http://127.0.0.1:8080”",
  "regex": "upstream sent too big header while reading response header from upstream",
  "domain": "nginx",
  "category": "protocol_error",
  "subcategory": null,
  "root_cause": "The upstream server's response headers exceed the default proxy_buffer_size (4KB), causing nginx to reject the response with a 502 error.",
  "root_cause_type": "generic",
  "root_cause_zh": "上游服务器的响应标头超过默认的 proxy_buffer_size（4KB），导致 nginx 拒绝响应并返回 502 错误。",
  "versions": [
    {
      "version": "nginx/1.18.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "nginx/1.20.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "nginx/1.24.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "nginx/1.26.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "proxy_buffers controls the number and size of buffers for the response body, not the initial header buffer.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "proxy_buffering off affects body buffering, not header buffering; the header buffer size is always limited by proxy_buffer_size.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "While this can fix the symptom, it requires application changes that may break features like session management or authentication.",
      "fail_rate": 0.4,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Increase proxy_buffer_size to 8K or larger (e.g., 16K) in the location or server block: `proxy_buffer_size 16k;`",
      "success_rate": 0.95,
      "how": "Increase proxy_buffer_size to 8K or larger (e.g., 16K) in the location or server block: `proxy_buffer_size 16k;`",
      "condition": "",
      "sources": []
    },
    {
      "action": "Also increase proxy_buffers to match for consistency: `proxy_buffers 8 16k;`",
      "success_rate": 0.9,
      "how": "Also increase proxy_buffers to match for consistency: `proxy_buffers 8 16k;`",
      "condition": "",
      "sources": []
    },
    {
      "action": "If the large header is due to many cookies, consider using a custom header compression or reducing cookie size at the application level as a long-term fix.",
      "success_rate": 0.7,
      "how": "If the large header is due to many cookies, consider using a custom header compression or reducing cookie size at the application level as a long-term fix.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "在 location 或 server 块中将 proxy_buffer_size 增加到 8K 或更大（例如 16K）：`proxy_buffer_size 16k;`",
    "同时增加 proxy_buffers 以保持一致：`proxy_buffers 8 16k;`",
    "如果大标头是由于过多 cookie 引起的，请考虑在应用程序级别使用自定义标头压缩或减少 cookie 大小作为长期修复。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.95,
  "resolvable": "true",
  "first_seen": "2024-08-12",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}