{
  "id": "nginx/upstream-sent-invalid-header-underscore",
  "signature": "upstream sent invalid header: \"X_Custom_Header: value\" while reading response header from upstream, client: 10.0.0.1, server: example.com",
  "signature_zh": "上游发送了无效标头：“X_Custom_Header: value”，同时从上游读取响应标头，客户端：10.0.0.1，服务器：example.com",
  "regex": "upstream sent invalid header: \".*_.*:.*\" while reading response header from upstream",
  "domain": "nginx",
  "category": "protocol_error",
  "subcategory": null,
  "root_cause": "Nginx by default discards HTTP headers containing underscores in the name, treating them as invalid per RFC 7230 due to potential inconsistencies with CGI/legacy systems.",
  "root_cause_type": "generic",
  "root_cause_zh": "Nginx 默认丢弃名称中包含下划线的 HTTP 标头，根据 RFC 7230 将其视为无效，因为可能与 CGI/遗留系统存在不一致。",
  "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": "While this works, it requires application changes that may not be feasible in all deployments; nginx can be configured to accept underscores.",
      "fail_rate": 0.4,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "ignore_invalid_headers controls general header validity, but underscore handling is controlled by the underscores_in_headers directive specifically.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The default behavior is intentional and unchanged across versions; a config change is required.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Enable underscores_in_headers in the http, server, or location block: `underscores_in_headers on;`",
      "success_rate": 0.95,
      "how": "Enable underscores_in_headers in the http, server, or location block: `underscores_in_headers on;`",
      "condition": "",
      "sources": []
    },
    {
      "action": "If security is a concern, rename the header in the upstream application to use hyphens (e.g., X-Custom-Header instead of X_Custom_Header) and update all clients.",
      "success_rate": 0.8,
      "how": "If security is a concern, rename the header in the upstream application to use hyphens (e.g., X-Custom-Header instead of X_Custom_Header) and update all clients.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use proxy_set_header to map the incoming header to a sanitized version: `proxy_set_header X-Custom-Header $http_x_custom_header;` (requires underscores_in_headers on or header name change).",
      "success_rate": 0.85,
      "how": "Use proxy_set_header to map the incoming header to a sanitized version: `proxy_set_header X-Custom-Header $http_x_custom_header;` (requires underscores_in_headers on or header name change).",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "在 http、server 或 location 块中启用 underscores_in_headers：`underscores_in_headers on;`",
    "如果担心安全问题，请在上游应用程序中将标头重命名为使用连字符（例如 X-Custom-Header 而不是 X_Custom_Header），并更新所有客户端。",
    "使用 proxy_set_header 将传入标头映射到清理后的版本：`proxy_set_header X-Custom-Header $http_x_custom_header;`（需要 underscores_in_headers on 或更改标头名称）。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://nginx.org/en/docs/http/ngx_http_core_module.html#underscores_in_headers",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.95,
  "resolvable": "true",
  "first_seen": "2024-06-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}