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.

saying these in an interview costs you the question

  • 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

resolving links…