Diagnosing and Fixing Tomcat 400 Bad Request Errors from Oversized Request Headers

Problem Overview

Clients receive an HTTP 400 Bad Request when Tomcat rejects a request. The server log contains messages such as Request header fields too large or Header size exceeds limit. The root cause is the maxHttpHeaderSize attribute on the Connector being smaller than the actual request header size.

Recognizable Symptoms

Symptom	Typical Log Entry	What to Check
400 Bad Request in browser or client	org.apache.catalina.connector.CoyoteAdapter - Request header fields too large	Inspect request headers
Client timeout or connection reset	Same header size error	Verify connector limits
Unexpected 500 errors after retry	Header size exceeded message	Check for proxy header injection

Diagnostic Checklist

1. Inspect Connector Configuration
   

   Open $CATALINA_BASE/conf/server.xml and locate the <Connector> element that handles HTTP traffic. Verify the maxHttpHeaderSize attribute. If it is missing, the default is 8 192 bytes.

   <Connector port="8080" protocol="HTTP/1.1" 
              maxHttpHeaderSize="65536" 
              connectionTimeout="20000" />

2. Capture a Sample Request
   

   Use curl or a browser dev‑tools network panel to view all headers sent for a typical request. Example using curl:

   curl -v -H "Large-Header: $(printf 'A%.0s' {1..70000})" http://localhost:8080/yourapp

   Count the total header size (bytes) manually or with a script.

3. Compare Header Size to Configured Limit
   

   If the request header size exceeds maxHttpHeaderSize, Tomcat will reject it.

4. Identify Additional Header Sources
   
   • Reverse proxies (NGINX, Apache HTTPD) that add X-Forwarded-For, X-Forwarded-Proto, or custom headers.
   • Application code that sets large cookies or custom authentication tokens.
   • Load balancers that inject health‑check headers.
5. Check for Custom Valves or Filters
   

   Some custom Valve implementations may impose their own header size limits.

Corrective Actions

1. Increase maxHttpHeaderSize
   

   Set the attribute to a value that comfortably exceeds the largest observed header. A common safe value is 64 KB (65 536 bytes). For Tomcat 9/10, edit server.xml or an appropriate context.xml:

   <Connector port="8080" protocol="HTTP/1.1" 
              maxHttpHeaderSize="65536" 
              connectionTimeout="20000" />

   After editing, restart Tomcat: catalina.sh stop && catalina.sh start (or the Windows equivalent).

2. Refactor Application Headers
   

   Review application code that sets headers. For example, avoid storing large tokens in cookies or move data to the request body. If a header is required, consider base64‑encoding it and trimming whitespace.

3. Coordinate with Upstream Proxies
   

   Ask the team managing NGINX or Apache HTTPD to reduce the size of injected headers or enable header compression. In NGINX, you can set proxy_buffer_size and proxy_buffers to accommodate larger headers.

4. Deploy a Reverse Proxy for Header Truncation
   

   If header size cannot be reduced, place a reverse proxy (e.g., NGINX) that strips or compresses headers before forwarding to Tomcat.

Verification Steps

• After restarting, resend the test request:

  curl -v -H "Large-Header: $(printf 'A%.0s' {1..70000})" http://localhost:8080/yourapp

  The expected result is a 200 OK response and no header‑size error in catalina.out.

• Monitor Tomcat memory usage. Use jvisualvm or top to ensure that the increased maxHttpHeaderSize does not cause abnormal heap growth.
• If a reverse proxy is used, repeat the test through the proxy and confirm that the header reaches Tomcat unchanged.

Escalation Criteria

• If increasing maxHttpHeaderSize does not resolve the 400 errors, investigate network devices, load balancers, or custom Valve code that may impose additional limits.
• If header size remains problematic and cannot be trimmed, consider redesigning the API to avoid large headers or implementing a dedicated header‑compression proxy.
• Escalate to security or network teams if anomalously large headers appear, as this may indicate a DoS attack vector.

Limitations and Risks

• Increasing maxHttpHeaderSize raises per‑request memory allocation and can increase garbage‑collection pressure under high load. Monitor heap usage and GC logs.
• Large headers can be exploited for denial‑of‑service attacks. Ensure that upstream firewalls or reverse proxies still enforce appropriate limits.
• Changes to server.xml require a Tomcat restart; schedule maintenance windows to avoid downtime.

Practical Checklist Summary

1. Verify maxHttpHeaderSize in server.xml.
2. Measure actual request header size with curl or dev‑tools.
3. Adjust maxHttpHeaderSize or refactor headers.
4. Restart Tomcat and retest.
5. Monitor memory and logs for regressions.

Following this diagnostic flow will quickly isolate the cause of 400 Bad Request errors due to oversized headers and guide you to an appropriate, safe fix.