When Nginx buffers POST requests, it holds the entire request body in memory or on disk before passing it to your backend application. This can cause delays, high memory usage, or timeouts for large uploads or streaming APIs. This guide shows you how to disable or tune that buffering so requests flow through immediately.
What You’ll Need
- Access to your Nginx configuration files (usually in
/etc/nginx/or/usr/local/nginx/conf/) - Ability to reload Nginx (root or sudo privileges)
- A basic understanding of Nginx server or location blocks
Step-by-Step
- Locate the relevant configuration file. Open your site’s config, typically
/etc/nginx/sites-available/your-siteor the mainnginx.conf. You’ll add directives inside aserverblock, or more precisely, inside alocationblock that handles the POST requests. - Disable request body buffering. Inside that
locationblock, add the directiveproxy_request_buffering off;. This tells Nginx to pass the request body to the backend as it arrives, without buffering the whole thing first. - Also disable proxy buffering (if needed). If you’re also seeing buffering of the response from your backend, add
proxy_buffering off;. This is separate from request buffering and controls the response side. - Adjust buffer sizes (optional). If you want to keep buffering but reduce its impact, set
client_body_buffer_size 16k;(or your desired size) andclient_max_body_size 100m;to allow larger uploads. These affect the per-request buffer and the maximum allowed body size. - Test the configuration. Run
nginx -tto check for syntax errors. If it reports OK, proceed. - Reload Nginx. Apply changes with
systemctl reload nginx(orservice nginx reloadon older systems). No downtime is needed. - Verify the change. Send a test POST request with a large body (e.g., using
curl --data-binary @bigfile) and watch your backend logs. If the request arrives immediately and is processed as data streams in, buffering is off.
Common Mistakes
- Putting the directive in the wrong block.
proxy_request_bufferingonly works insidelocationorserverblocks that have aproxy_pass. Putting it inhttporeventswill cause an error. - Forgetting to reload. Editing the file but not reloading Nginx leaves the old config active. Always test and reload.
- Confusing request buffering with response buffering. They are controlled by different directives. If you only disable request buffering, the response may still be buffered.
- Disabling buffering globally. If you set
proxy_request_buffering offin thehttpblock, it applies to all virtual hosts, which may not be intended. Scope it to specific locations.
Tips
- Use only where needed. Disabling request buffering can increase the load on your backend because it now receives data in chunks. For normal small POSTs, keep buffering enabled for better performance.
- Consider timeouts. With buffering off, slow clients can tie up backend connections longer. Adjust
proxy_read_timeoutandproxy_send_timeoutto avoid premature disconnects. - Monitor memory. If you set
client_body_buffer_sizehigh, many concurrent large uploads could exhaust memory. Keep it reasonable or rely on disk buffering. - Use for streaming APIs. If you’re building a streaming upload or a chat application, disabling request buffering is essential for real-time data flow.
Troubleshooting
Change doesn’t take effect. Make sure you edited the correct file. Use nginx -T to dump the full effective configuration and grep for your directive to confirm it’s present.
Nginx fails to reload. Run nginx -t to see the error. Common issues: directive not allowed in that context, missing semicolon, or a typo. Fix and test again.
Backend still sees buffered data. Check if you have a reverse proxy like Apache or another Nginx layer in front. Each hop may have its own buffering settings.
Uploads time out. With buffering off, the backend must read the body as it comes. If your backend isn’t streaming, it might wait for the full body and time out. Increase proxy_read_timeout or handle streaming in your app.
Memory usage spikes. If you raised client_body_buffer_size, reduce it back. Nginx will use disk buffering for larger bodies, which is slower but safer.
Frequently Asked Questions
What exactly does proxy_request_buffering off do?
It tells Nginx to forward the request body to the backend as it receives it, without storing the entire body first. This is useful for large uploads or streaming data.
Will disabling buffering break normal form submissions?
No. Small POST bodies will still be sent correctly. The only difference is that Nginx won’t accumulate the full body before sending; it sends chunks immediately.
How do I set a maximum upload size?
Use client_max_body_size. For example, client_max_body_size 200m; allows files up to 200 MB. This works independently of buffering.
Can I disable buffering only for specific URLs?
Yes. Put the directive inside a location block that matches those URLs, e.g., location /upload/ { proxy_request_buffering off; ... }.
Does this work with WebSocket or SSE?
For WebSocket, Nginx already handles upgrades specially. For Server-Sent Events, you may also need proxy_buffering off to stream responses. Request buffering is less relevant there.
Is there a downside to disabling buffering?
Yes. It can increase backend load and make your service more vulnerable to slow clients. Use it selectively and consider rate limiting or timeouts.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Arctic Sea Ice Forecasts Disagree: What to Do
- MySQL Workbench to VPS: SSH Tunnel Setup
- Bluesky Beginners Guide: How to Get Started5.00 min/km
- Scale a Small Business Without Losing Culture
- LG V20 Won’t Turn On? Fixed
- Snagit vs Camtasia: Which One Do You Need?