Nginx Drops Header Parameters with Underscores by Default – How to Enable Them

Nginx is a high‑performance HTTP and reverse‑proxy server that has become a standard component in Java web applications, often used to improve throughput and availability.

The author describes a common integration scenario where system A calls system B; after migrating system B and updating the endpoint, a header named my_token no longer reaches the backend while other parameters work.

To reproduce the issue, a minimal Spring Boot "Hello World" controller is created:

@RestController
@RequestMapping("/para")
public class ParameterController {
    @GetMapping("hello")
    public String helloworld(HttpServletRequest request) {
        return "Hello World！";
    }
}

When accessed directly via Postman on port 8081, the service receives the my_token header correctly.

After placing Nginx in front of the service with a simple location block:

location / {
    proxy_pass http://localhost:8081/para/;
}

the same request (now sent to http://localhost/hello ) results in the my_token header being null, even though it is present in the request.

Investigation reveals that Nginx’s default setting underscores_in_headers is off, causing it to drop any request header containing an underscore.

Adding the following directive to the Nginx configuration and reloading fixes the issue:

underscores_in_headers on;

After the change, debugging shows that the my_token header is received correctly, confirming the root cause.

The article highlights that such configuration nuances belong to operations and can lead to prolonged troubleshooting if overlooked.