nginx protocol_error ai_generated true

upstream sent invalid header: "X_Custom_Header: value" while reading response header from upstream, client: 10.0.0.1, server: example.com

ID: nginx/upstream-sent-invalid-header-underscore

Also available as: JSON · Markdown · 中文
95%Fix Rate
88%Confidence
1Evidence
2024-06-05First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
nginx/1.18.0 active — — —
nginx/1.20.0 active — — —
nginx/1.24.0 active — — —
nginx/1.26.0 active — — —

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.

generic

中文

Nginx 默认丢弃名称中包含下划线的 HTTP 标头，根据 RFC 7230 将其视为无效，因为可能与 CGI/遗留系统存在不一致。

Official Documentation

https://nginx.org/en/docs/http/ngx_http_core_module.html#underscores_in_headers

Workarounds

  1. 95% success Enable underscores_in_headers in the http, server, or location block: `underscores_in_headers on;` 
    Enable underscores_in_headers in the http, server, or location block: `underscores_in_headers on;`
  2. 80% success 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. 
    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.
  3. 85% success 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). 
    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).

中文步骤

  1. 在 http、server 或 location 块中启用 underscores_in_headers：`underscores_in_headers on;`
  2. 如果担心安全问题，请在上游应用程序中将标头重命名为使用连字符（例如 X-Custom-Header 而不是 X_Custom_Header），并更新所有客户端。
  3. 使用 proxy_set_header 将传入标头映射到清理后的版本：`proxy_set_header X-Custom-Header $http_x_custom_header;`（需要 underscores_in_headers on 或更改标头名称）。

Dead Ends

Common approaches that don't work:

  1. 40% fail

    While this works, it requires application changes that may not be feasible in all deployments; nginx can be configured to accept underscores.

  2. 70% fail

    ignore_invalid_headers controls general header validity, but underscore handling is controlled by the underscores_in_headers directive specifically.

  3. 90% fail

    The default behavior is intentional and unchanged across versions; a config change is required.