For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Limit request header size
Set a maximum total size for the headers of incoming HTTP requests.
Set the maximum total size of the headers that Envoy accepts on incoming requests.
By default, Envoy accepts request headers with a total size of up to 60 KiB. When a request exceeds the limit, Envoy rejects the request before it reaches your upstream services. Envoy returns a 431 Request Header Fields Too Large response for HTTP/1.x connections and resets the stream for HTTP/2 connections.
You might want to change the limit in the following cases:
- Lower the limit to protect your backends from oversized requests and to reduce the memory that each request can use in the gateway proxy.
- Raise the limit for clients that send large headers, such as large cookies or tokens. Your backends might enforce their own header size limits. To find out where a
431response comes from, check its headers. A431response from a backend includes thex-envoy-upstream-service-timeheader, but a431response from the gateway proxy does not.
Note
The limit applies to the total size of all request headers, including the names and values of headers that HTTP clients add automatically. For example, curl always sends the Host, User-Agent, and Accept headers. To limit the number of headers instead of their size, see Limit request header count.
Before you begin
Follow the Get started guide to install kgateway.
Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.
Get the external address of the gateway and save it in an environment variable.
export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}") echo $INGRESS_GW_ADDRESS
Set a maximum header size
Create a ListenerPolicy with the
maxRequestHeadersKbsetting. This example sets a low limit of 1 KiB so that you can test it with a single large header.kubectl apply -f- <<EOF apiVersion: gateway.kgateway.dev/v1alpha1 kind: ListenerPolicy metadata: name: max-request-headers-size namespace: kgateway-system spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: http default: httpSettings: maxRequestHeadersKb: 1 EOFReview the following table to understand this configuration. For more information about the available fields, see the API reference.
Setting Description spec.targetRefsThe Gateway that this policy applies to. The policy applies to all HTTP and HTTPS listeners on the Gateway. spec.default.httpSettings.maxRequestHeadersKbThe maximum total size of request headers in KiB. Requests that exceed this limit receive a 431response for HTTP/1.x and a stream reset for HTTP/2 connections. Must be between1and8192. If unset, Envoy’s default of60KiB is used.Send a request to the httpbin app with a 500-byte header. The total size of the request headers is under the limit of 1 KiB. Verify that you get back a 200 HTTP response code.
curl -i http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com" \ -H "x-large-header: $(head -c 500 /dev/zero | tr '\0' a)"Example output:
HTTP/1.1 200 OK ...Send another request with a 2,000-byte header so that the total size of the request headers exceeds the limit of 1 KiB. Verify that the gateway proxy rejects the request with a
431 Request Header Fields Too Largeresponse.curl -i http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com" \ -H "x-large-header: $(head -c 2000 /dev/zero | tr '\0' a)"Example output: The response does not include the
x-envoy-upstream-service-timeheader, because the gateway proxy rejects the request before it forwards it to the httpbin app.HTTP/1.1 431 Request Header Fields Too Large content-length: 31 content-type: text/plain date: Wed, 11 Nov 2026 16:19:26 GMT server: envoy connection: close Request Header Fields Too Large
Cleanup
You can remove the resources that you created in this guide.kubectl delete listenerpolicy max-request-headers-size -n kgateway-system --ignore-not-found