Skip to content 
NGINX Buffering determines how quickly and efficiently your proxy receives responses from the upstream server, buffers them, and sends them to clients. I'll show you how I reduce latency, release backend connections early, and the Memory keep it under control.
Key points
The following key considerations help me strike the right balance between performance and memory usage.
- Decoupling Reducing the distance between the client and the backend reduces connection time and increases throughput.
- Buffer Sizes Select "exact" to save RAM and avoid disk I/O.
- busy buffers Limit active memory during transmission.
- Streaming Exceptions operate smoothly without buffering.
- Monitoring and load tests validate every change.
How Proxy Buffering Works in NGINX
I use active Buffering, so that NGINX can quickly retrieve responses from the upstream server and then deliver them to clients on its own. This decoupling reduces the Latency on the backend, because the application finishes processing faster and closes its connection sooner. While clients load at varying speeds, the proxy layer throttles the data sent from memory. If the data does not fit entirely in RAM, NGINX can temporarily fall back to files and still reliably forward the response. It is precisely this behavior that stabilizes heavily loaded systems with many concurrent Connections.
When Active Buffering Is the Best Choice
For traditional web apps, APIs with moderate response sizes, or WordPress stacks, it provides Buffering consistently delivers the best results. I offload the backend earlier, while NGINX handles the rest of the traffic to what are often mixed client networks. This increases the effective Throughput, especially when many requests are running at the same time. Anyone who bundles multiple services behind a reverse proxy also benefits from controlled load balancing. When it comes to architectural questions about proxies, a clear Reverse proxy architecture, which clearly separates roles and limits.
Storage vs. I/O: Setting the Right Budget
I balance RAM and disk access because buffers that are too small cause unnecessary Disk I/O trigger and cause buffers that are too large to bloat the memory per connection. The key factors are typical response sizes, parallel requests, and the actual Client Speed. Ideally, small responses remain entirely in RAM, allowing NGINX to stream them to slower recipients without any delay. Very large response bodies may end up on disk, but in that case I make sure to use fast drives and set limits to prevent excessive I/O. This balance keeps the Response times low and protects the system from storage pressure.
Overview of Guidelines and Reference Values
I specifically set the key parameters to control memory and transmission behavior. The first buffer for the response headers is appended to proxy_buffer_size; it prevents oversized header errors and avoids unnecessary page faults. I distribute the actual response data across proxy_buffers as pairs of count and size, so that bodies remain entirely in RAM, as long as this is realistic. With proxy_busy_buffers_size I limit the number of buffers already marked for shipment to curb active memory usage. I base typical sizes on memory pages (4–32 KB) and the known response profiles of my applications.
| directive | Effect | Typical values | Notes |
|---|---|---|---|
| proxy buffering | On/Off of buffering | on (Default) | Leave enabled for standard web apps; check for live streaming |
| proxy_buffer_size | Header buffer | 8k–16k | If it's too small, it results in an „upstream sent too big header“ error.“ |
| proxy_buffers | Body Buffer | 8 16k, 16 16k | Link to response sizes and parallelism |
| proxy_busy_buffers_size | Send Buffer Limit | 32k–128k | Sufficient throughput without tying up RAM |
| proxy_max_temp_file_size | Disk Limit | 0–1 g | 0 Disables temporary files |
| proxy_temp_path | Path for temporary files | SSD Path | Save to a high-speed storage medium |
Practical Profiles and Sample Calculations
I roughly calculate the memory requirements per active connection as the sum of proxy_buffer_size plus (N × buffer size) from `proxy_buffers`. With 8 16k buffers plus a 16k header, we end up with about 144 KB per request, as long as everything stays in RAM. So, with 5,000 concurrent requests, I estimate about 720 MB of pure buffer usage, plus the overhead of the Processes. As traffic scales, so does demand—that's why I set buffers so that typical responses fit without treating outliers with oversized bodies as the norm. Where necessary, I limit exceptions with Disk Limits, to handle memory spikes.
When I intentionally turn off buffering
Real-time APIs, server-sent events, or live video require direct Throughput without additional buffering. In such cases, I disable `proxy_buffering` and rely on efficient Streaming. The proxy then forwards the data immediately, which prevents latency spikes for live data but keeps the backend connection open longer. For these patterns, it’s worth taking a look at Response streaming, including appropriate keepalive and timeout tuning. It remains important to keep an eye on the higher resource consumption per connection and to set limits accordingly.
Setting Busy Buffers in a Targeted Manner
With proxy_busy_buffers_size I control how much „ready-to-send“ memory remains blocked at any given time. If the limit is set too low, delivery slows down; if it’s set too high, RAM spikes increase. I therefore choose a value that is 1–2 times the buffer size so that NGINX can push packets through quickly without using too much Memory to bind. For slow clients, I accept a little more busy space to reduce the risk of frequent context switches. Fast networks benefit from lower values, which Memory requirement keep it predictable.
Temporary Files: Path, Size, Limits
I'm enabling temporary Files only when large bodies are rendered realistically or RAM is limited. If temp files are stored on an SSD, response times remain acceptable; on a slow disk, I/O quickly slows down the entire Reply Thread. I use `proxy_max_temp_file_size` to protect against excessive memory usage; if in doubt, I set a hard limit. If there are many large, concurrent responses, I allocate sufficient space and monitor the actual utilization. Where RAM is available, I prefer larger buffers and keep critical parts in the Memory.
Iterative Tuning, Metrics, and Tests
I start with conservative Values, measure, adjust, and repeat the cycle. Important metrics include latency, error rate, RAM spikes, I/O wait times, and utilization of the Worker. Load tests reveal effects that go unnoticed in everyday use, such as header spikes caused by cookies or rare mega-responses. In addition, I fine-tune connection and worker parameters in conjunction with one another, such as Worker Connections and keepalive. I review every change carefully to assess the impact of the Buffer can clearly identify.
Request Buffering and Uploads
Response buffers are only half the story. On the input side, proxy_request_buffering, whether NGINX buffers client bodies (e.g., uploads) in their entirety first or streams them immediately to the upstream server. For APIs that receive large files, I often disable request buffering: The upstream sees the data stream sooner, timeouts are reduced, and NGINX doesn’t have to temporarily store large bodies on disk. The downside: The upstream connection remains open longer and is more dependent on the client’s speed. For traditional forms or smaller JSON requests, I keep request buffering enabled to smoothly handle traffic spikes and better manage server resources. I combine this with client_max_body_size and a matching client_body_buffer_size, so that outliers are rejected early on or appropriately buffered.
Controlling Pro-Response: X-Accel-Buffering, Chunked, and Lengths
For fine-grained control, I disable buffering on a per-response basis via X-Accel Buffering From the upstream: The „X-Accel-Buffering: no“ header instructs NGINX to stream the response directly, even if `proxy_buffering` is enabled globally. I use this for SSE, long polling, or diagnostic streams without sacrificing general performance tuning. In addition, I make sure that Content-Length, where possible: If NGINX knows the length, it can plan buffers and temporary files more predictably than if it were to rely exclusively on chunked is transferred. If the length is unknown (e.g., live streams), I make a conservative estimate of the required capacity and ensure I/O with limits. For error pages or small JSON responses, I keep buffering strictly enabled so that the upstream connection is released early.
Compression and Protocols: A Look at HTTP/2 and HTTP/3
Compression and buffering must be considered together. Is gzip or if Brotli is enabled, compression benefits from contiguous data blocks in RAM. Buffers that are too small can limit throughput because the compressor has to switch context more frequently. I therefore choose buffer sizes that effectively bundle typical response segments without letting RAM usage get out of hand for each connection. Under HTTP/2 and HTTP/3 With multiplexing and flow control, the transmission speed varies by stream; buffering stabilizes the backend, while NGINX neatly synchronizes the streams. Important: On paths that are very sensitive to latency, reducing the busy space by a tick can help mitigate head-of-line effects; on „fat“ lines with large windows, I allocate a little more busy space to maintain maximum transmission performance.
Proxy Cache and Range Requests: Interaction with Buffers
Who proxy_cache When using NGINX, the budgets for buffers and temp files should be coordinated. NGINX can cache responses and deliver them to clients simultaneously; sufficient RAM buffers shorten the duration of the backend connection, while a cache hit completely decouples subsequent requests. I impose stricter limits on temporary files when the cache is warm, and I allow them as long as the hit rate is building up. When Range Inquiries (Partial downloads) I decide whether to serve them directly from the cache or to let them buffer completely first. Frequent requests for large files benefit from carefully balanced buffer sizes and optional segmented responses, ensuring that neither disk I/O nor RAM gets out of control.
Slow Clients: Managing Throughput Without Overloading RAM
Most of the buffering effects are only noticeable with very slow clients. I set send_timeout and optional limit_rate/limit_rate_after, to protect slow-responding clients without unduly tying up workers. If throttling is severe, busy buffers must increase; otherwise, stalls may occur. At the same time, I control the number of parallel connections per IP address to mitigate abnormal patterns. For downloads with a mixed client base (mobile, Wi-Fi, fiber), moderate busy values and slightly more generous body buffers help ensure that NGINX pushes data linearly while the upstream server is already busy with the next request.
Container-Based Operations and Orchestration
I plan to do that in containers proxy_temp_path Note: Either a fast host volume (SSD) or a tmpfs, if there is enough RAM available. Container limits (memory/CPU/ephemeral storage) directly affect buffers and temp files; I maintain enough headroom for peaks and adjust the number of parallel workers and connections accordingly. It remains important to ulimit -n (file descriptors) and the Orchestrator quotas: If the ephemeral storage is too small, temp files result in errors; if RAM is too scarce, workers crash under OOM pressure. I size buffers so that typical load spikes remain stable within the container limits, and I continuously monitor the actual space requirements of the temp directories.
Initial Values and Blueprints for Common Web Apps
As a solid starting point, I use a brief profile, which I then refine with measured values. Example:
location / {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering on;
# Header and Body Buffers
proxy_buffer_size 16k;
proxy_buffers 16 16k;
proxy_busy_buffers_size 64k;
# Temp Files Only as a Fallback
proxy_max_temp_file_size 256m;
proxy_temp_path /var/cache/nginx/proxy_temp 1 2;
# Timeouts & Sending
proxy_read_timeout 60s;
send_timeout 30s;
# Optional: Upload streaming depending on the API
# proxy_request_buffering off;
}
This ensures that medium-sized responses remain entirely in RAM, the upstream connection is freed up early, and tempfiles are only used in the event of outliers. In the second round, I adjust the buffer count to match the actual level of parallelism; if necessary, I slightly increase the busy size for short, frequent responses, and I impose stricter limits on temp files as soon as the cache hit rate improves.
Monitoring and Logging: Making the Impact Visible
I measure consistently: $request_time and $upstream_response_time in the access log, indicate whether the upstream connection is terminated early. $bytes_sent and $body_bytes_sent help align buffer profiles with actual traffic. If the difference between the upstream time and the total duration decreases, the buffers are working properly. I correlate this with RAM spikes, I/O wait, and the utilization of the proxy_temp_path. In stress tests, I vary client speeds, response sizes, and header load (e.g., cookies) to identify edge cases. Only when log metrics and system values are consistently within my target range do I freeze the profile and document limits and escalation paths (larger buffers, different temp policies, additional replicas).
Common Problems and How to Fix Them
The message „Upstream sent a header that was too large“I resolve this by increasing the `proxy_buffer_size` and, if necessary, the size of the `proxy_buffers`. If timeouts occur on slow end devices, I moderately increase the send timeouts and give the busy buffers a little breathing room. If the temp directory fills up, I lower the maximum size or increase the RAM buffers, depending on the cost-benefit analysis. If delivery becomes choppy, I check for I/O bottlenecks, CPU saturation, and the distribution of the Buffer. When dealing with shortages, I always start by looking at the actual figures, not by simply doubling the amounts across the board.
Conclusion: My Checkpoints for NGINX Proxy Buffering
First, I'll define typical Response sizes, peak load, and client profiles before I even adjust the buffer sizes. After that, I set a header buffer that’s large enough so I don’t run into any unnecessary errors. I size the body buffers so that typical responses stay in RAM and only exceptions are written to Disc fall. I configure Busy Buffers so that transfers run smoothly without wasting memory. Finally, I test everything with load tests and monitoring until latency, throughput, and memory usage are within a reliable Windows lie.
