Nginx proxy_buffering: the one setting that quietly breaks your backend under load

So you have nginx proxying to a slow backend. Maybe it's a streaming endpoint, maybe it's a legacy service with occasional slow queries. Under normal load everything works fine. Then traffic spikes and suddenly you're getting 502s, timeouts, or your OOM killer fires.

The culprit is often nginx's default buffering behavior.

What happens

By default, nginx buffers the entire backend response before sending anything to the client. This is meant to improve performance when the backend is faster than the client. But when your backend is slow or streams data, nginx will hold the full response in memory (or disk, if it exceeds proxy_max_temp_file_size) before passing it along.

During this time, that nginx worker is tied up. Enough slow responses and you run out of workers, new requests queue up, and things go downhill fast.

The fix

location /slow-endpoint/ {
    proxy_pass http://backend;
    proxy_buffering off;
    proxy_buffer_size 4k;
}

proxy_buffering off tells nginx to stream the response straight through instead of buffering it. The client gets data as it arrives, workers don't get blocked.

The gotcha with proxy_max_temp_file_size

Even with buffering on, nginx can spill to disk. The default is 1024m. If you have many slow responses, this can fill your disk and cause the same problem. Either set it to 0 to disable disk spilling entirely, or monitor your error logs for buffer-related messages.

How to diagnose

If you're not sure whether buffering is your issue, check these:

• strace on nginx workers — look for large writes to temp files
• lsof on nginx workers — check for open temp files in the nginx tmp directory
• error log during load — buffer-related errors show up here
• tcpdump if it's localhost — see if responses come back in one chunk or streamed

When to leave buffering on

Buffering is fine when your backend is fast and responses are small. It reduces backend load because nginx can serve cached responses without hitting the backend again. The issue only surfaces with slow or streaming backends.

The fix is a single line. The diagnosing is the part that takes time if you don't know where to look.

---

Tags: nginx, devops, sysadmin, performance