Tune Kong Gateway for large payloads

Kong Gateway is optimized for API traffic. Most payloads are small JSON documents in the range of a few bytes to 10 KB. When your deployment handles larger payloads (SOAP/XML responses from legacy services, file uploads, batch operations, or web-oriented traffic like HTML and images), the default buffer configuration needs tuning to maintain throughput and protect against resource exhaustion.

By default, Kong Gateway does not stream request and response bodies. It reads the entire payload into memory before forwarding it:

1. The client sends a request. Kong Gateway reads the bytes into a request buffer until the full request is received.
2. Kong Gateway processes the request and forwards it to the upstream.
3. The upstream sends a response. Kong Gateway reads it into a response buffer until the full response is received.
4. Kong Gateway forwards the complete response to the client.

 
sequenceDiagram
    participant Client
    box Kong
        participant RB as Request buffer
        participant RSB as Response buffer
    end
    participant Upstream

    Client->>RB: Request
    RB->>Upstream: Forward request
    Upstream->>RSB: Response
    RSB->>Client: Forward response
  

With default buffering enabled, the upstream does not receive the request body until Kong Gateway has buffered it from the client. For responses, Kong Gateway begins forwarding data to the client only after it has buffered some of the response from the upstream, and may continue streaming as more data arrives. Each buffer is allocated per request, so buffer sizes compound quickly under load.

Kong Gateway uses the following configuration options to buffer incoming requests:

When request buffers are exceeded

If the total size of the request headers exceeds the combined size of nginx_http_client_header_buffer_size and nginx_http_large_client_header_buffers, Kong Gateway returns a 414 or 400 error.

There are two separate controls for the request body because they serve different purposes. When the body exceeds nginx_http_client_body_buffer_size but is within nginx_http_client_max_body_size, Kong Gateway spills the excess to disk rather than rejecting the request. When the body exceeds nginx_http_client_max_body_size, Kong Gateway returns a 413 error.

If a plugin reads the request body and the body exceeds nginx_http_client_body_buffer_size, the plugin will fail. See the PDK documentation for details.

Kong Gateway uses two configuration options to buffer upstream responses:

When response buffers are exceeded

If the response headers from the upstream exceed nginx_http_proxy_buffer_size, Kong Gateway returns a 502 error and logs:

upstream sent too big header while reading response header from upstream

Increasing `nginx_http_proxy_buffer_size` resolves this error.

If the response body exceeds the total size of `nginx_http_proxy_buffers`, Kong Gateway spills the excess to disk. 
When that happens, increase `nginx_http_proxy_buffers` or disable response buffering for that Route. 
For large responses where Kong Gateway is not inspecting or modifying the body (more than a few megabytes), disabling buffering is the better option.

## Disk buffering and performance

When Kong Gateway spills to disk, performance degrades for all concurrent requests, not just the large one. Kong Gateway uses a non-blocking event loop to handle many requests concurrently on a single thread. Disk I/O is a blocking system call on Linux, so one disk-buffered request stalls the event loop and increases latency for everything running at the same time.

Kong Gateway logs when disk buffering occurs:

a client request body is buffered to a temporary file an upstream response is buffered to a temporary file

Monitor these log messages alongside disk I/O on Kong Gateway nodes. When they appear consistently, either increase the relevant buffer size or disable buffering for that Route. You can also set nginx_http_proxy_max_temp_file_size to 0 to prevent Kong Gateway from spilling response bodies to disk at all. Kong Gateway will stream the response instead.

Buffers are allocated per request. At 1,000 concurrent requests, increasing a buffer size by 1 MB adds roughly 1 GB of memory consumption. The actual impact varies depending on traffic shape, network speeds, and OS settings, so test Kong Gateway under realistic load when tuning buffer sizes. Increasing by a few memory pages at a time (each page being 4 KB) is safer than making large jumps.

For large payloads where buffering is impractical, you can disable it per Route:

• request_buffering: false: Kong Gateway streams the request body to the upstream as the client sends it.
• response_buffering: false: Kong Gateway streams the response body to the client as the upstream sends it.

Disabling buffering also helps when optimizing for Time To First Byte (TTFB), since the client starts receiving data as soon as the upstream begins sending it rather than waiting for the full response to be buffered.

Disabling buffering only applies to the body. Headers are always buffered. At typical sizes, this adds negligible overhead.

By default, Kong Gateway buffers because reading and writing to a network socket requires a syscall. Streaming data in small chunks increases syscall frequency and CPU usage. Buffering reduces that overhead, which is the right default for small API payloads that fit in memory.

Disabling buffering exposes the upstream to slow clients, including Slowloris attacks. Use an authentication or authorization plugin to protect the upstream when buffering is disabled.

Kong Gateway treats all clients as untrusted. Strict buffer limits prevent a malicious client from sending oversized requests that cause unbounded consumption of CPU, memory, disk, or network resources.

Avoid reading or modifying large request or response bodies inside Kong Gateway plugins. Processing large bodies adds latency and reduces throughput for all requests, regardless of payload size.

The following table shows which Nginx directives the kong.conf buffering options map to: