Skip to content

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

Page as Markdown

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 431 response comes from, check its headers. A 431 response from a backend includes the x-envoy-upstream-service-time header, but a 431 response 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

  1. Follow the Get started guide to install kgateway.

  2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

  3. 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

  1. Create a ListenerPolicy with the maxRequestHeadersKb setting. 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
    EOF

    Review the following table to understand this configuration. For more information about the available fields, see the API reference.

    SettingDescription
    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 431 response for HTTP/1.x and a stream reset for HTTP/2 connections. Must be between 1 and 8192. If unset, Envoy’s default of 60 KiB is used.
  2. 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
    ...
    
  3. 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 Large response.

    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-time header, 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
Was this page helpful?