skip to content

When and why would you change `server.max-http-request-header-size`, and what are the tradeoffs?

level: principalimportance: should knowfreq 34%

answer

  1. server.max-http-request-header-size, default 8KB
  2. server-agnostic (Tomcat/Jetty/Undertow)
  3. big JWT / SPNEGO / many cookies → 400/431
  4. bigger buffer = memory/DoS surface × connections
  5. also tune proxy (nginx large_client_header_buffers)

basics

~10 s

server.max-http-request-header-size (default 8KB) caps the total size of incoming HTTP request headers. Raise it when large headers (big JWTs, many cookies) cause 400/431 errors; keep it bounded to avoid memory-abuse attacks.

solid answer

~50 s

`server.max-http-request-header-size` is a server-agnostic Spring Boot property (applies to Tomcat, Jetty, Undertow) bounding the **total size of the HTTP request header section**. Default is 8KB. It exists because header buffers are allocated per connection and unbounded headers are a memory-abuse / DoS vector, so the server rejects oversized headers with a 400 Bad Request (or 431 Request Header Fields Too Large). You raise it when legitimate requests carry large headers: fat JWT/OAuth bearer tokens, SAML assertions, Kerberos/SPNEGO Negotiate tokens, or many/large cookies — symptoms are intermittent 400/431 responses that correlate with header growth. The tradeoff: a higher limit means larger per-connection buffers and a wider abuse surface, so raise it deliberately (e.g. 16KB or 32KB) rather than to an enormous value. Better long-term fixes often reduce header size instead — trim token claims, move state out of cookies — because the header path is on every request.

code

yaml · 7 lines
yaml
server:
  max-http-request-header-size: 16KB   # default 8KB; raise for large JWT/SPNEGO tokens or many cookies
  tomcat:
    max-connections: 8192
# Memory note: header buffer is per connection, so the effective worst case scales
# with max-connections. Prefer shrinking tokens/cookies over an unbounded raise,
# and remember upstream proxies (nginx large_client_header_buffers) have their own caps.

go deeper

for a junior

May not know this property; recognizing 400/431 relates to header size is enough.

for a middle

Knows the 8KB default and that large tokens/cookies require raising it.

for a senior

Explains the memory/DoS tradeoff and the server-agnostic nature; checks proxy limits.

for a principal

Treats header size as a cross-hop budget and argues token-design fixes over ever-raising limits, quantifying buffer × max-connections.

## What the property is `server.max-http-request-header-size` is one of Spring Boot's **server-agnostic** properties: it lives directly under `server.*` (not `server.tomcat.*`) and Spring maps it to the underlying container's equivalent — Tomcat `maxHttpRequestHeaderSize`, Jetty/Undertow analogues. It bounds the **combined size of the request line plus all HTTP request headers** (not the body). - **Default: 8KB** (8192 bytes). - Accepts a `DataSize`, so `8KB`, `16KB`, `32768`, etc. ## Why the limit exists When a connection arrives, the server allocates a buffer to read and parse the header block. If headers were unbounded, a malicious client could send megabytes of headers per connection and exhaust memory across many connections — a denial-of-service vector. The cap makes the server **reject** anything larger before committing resources, typically with **HTTP 400 Bad Request** or **431 Request Header Fields Too Large**. ## When you legitimately need to raise it Real traffic sometimes has genuinely large headers: - **Large JWTs / OAuth2 access tokens** with many claims or embedded roles, sent in the `Authorization: Bearer …` header. - **SAML** assertions or **Kerberos/SPNEGO** `Authorization: Negotiate …` tokens (can be several KB). - **Many cookies** or large session/CSRF cookies, especially behind SSO that stacks cookies. - Verbose custom headers, tracing baggage, or forwarded-header chains behind multiple proxies. **Symptom:** intermittent `400`/`431` responses that appear only for certain users (e.g. those in many AD groups → bigger token) or grow over time. ## The tradeoffs and how to decide - **Raising it** (e.g. to 16KB/32KB) fixes the errors but enlarges per-connection buffers and widens the abuse surface, since this path runs for **every** request. Multiply by `max-connections` to see the memory implication. - **Prefer reducing header size** when feasible: trim JWT claims, use reference tokens / opaque tokens with server-side lookup, move data out of cookies, collapse proxy-forwarded headers. This is usually the more robust fix. - Set it as a **deliberate, bounded** value — never disable or set an enormous cap on internet-facing endpoints. ## Gotchas - **Proxies have their own limits.** Even if you raise Tomcat's limit, an upstream Nginx (`large_client_header_buffers`), ALB, or CDN may reject the request first. Tune the whole chain. - **Response headers are separate** — this property is about *request* headers; response header size is a different concern. - **Body size is unrelated** — that's `spring.servlet.multipart.max-request-size` / `max-file-size` for uploads, not this. - Because it's server-agnostic, switching from Tomcat to Undertow/Jetty keeps the same property working — no per-container rename. ## Principal-level framing Treat header size as a system-wide budget: the app-server limit is only one hop. The right decision balances (a) accommodating legitimate large tokens across the whole proxy chain vs. (b) minimizing per-request memory and DoS surface — and frequently the strategic answer is to shrink what goes in headers (token design) rather than perpetually raising limits.

  • Users in many AD groups intermittently get HTTP 400/431 while others don't. What's the likely cause and fix?
    Their JWT/Kerberos token carries more claims/roles, pushing the header block past the 8KB default. Raise `server.max-http-request-header-size` (and the matching proxy limit), or better, reduce token size (fewer embedded claims, reference/opaque tokens).
  • You raised the Spring Boot limit but requests still fail with a header error. What did you miss?
    An upstream proxy/CDN/load balancer has its own header-size cap (e.g. Nginx `large_client_header_buffers`) and rejects the request before it reaches the app server. The whole hop chain must be tuned.
  • Is raising this limit or shrinking the tokens the better fix?
    Usually shrinking tokens: the header path executes on every request, so smaller headers reduce memory and DoS surface permanently, whereas raising the limit widens the abuse surface and only defers the problem.

  • Confusing it with request body / multipart size limits
  • Thinking it's Tomcat-only (it's server-agnostic under server.*)
  • Setting it huge or disabling it on public endpoints
  • Forgetting upstream proxies impose their own header-size caps

context