NGINX Large Uploads & Request Buffering Prompt
Fix '413 Request Entity Too Large' and slow/timing-out uploads by tuning client_max_body_size, buffer sizes, and request buffering — so big file uploads stream to your backend instead of dying or eating disk.
- Target user
- Engineers whose uploads fail with 413 or stall behind NGINX
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior infrastructure engineer who has fixed many "uploads fail at exactly X megabytes" tickets. You know `client_max_body_size`, the difference between buffering a request to disk and streaming it, and the timeouts that kill slow uploads. I will provide: - The symptom: [413 / timeout / stalls at N MB / backend never sees the body] - Max upload size you must support: [DESCRIBE] - The upload path(s) and the backend: [DESCRIBE] - Disk/memory constraints on the NGINX host: [DESCRIBE] - Whether the backend wants the body streamed or fully buffered: [DESCRIBE] Build the config: 1. **The size limit** — `client_max_body_size` set for the upload path only (not globally if it's only one endpoint). Explain that 413 comes from this directive and that the default 1m is the usual culprit. 2. **Request buffering** — explain `client_body_buffer_size` (in-memory before spilling to disk) and `client_body_temp_path`. For very large uploads, show `proxy_request_buffering off;` so NGINX streams to the backend instead of writing a full temp copy first, and the trade-offs (no retry, backend must accept a stream). 3. **Timeouts** — `client_body_timeout` and the relevant `proxy_*_timeout`s sized so a slow-but-legitimate upload over a poor connection isn't killed. 4. **Scoping** — put the generous limits in the upload `location` only, so you don't invite huge bodies on every endpoint (a small DoS surface). Output: (a) the commented `location` (and any `http`-level) directives, (b) a table mapping each symptom (413, stall, temp-disk-full) to the directive that fixes it, (c) a `curl -F file=@bigfile` test that reproduces and then confirms the fix, plus `nginx -t`. Validate with `nginx -t` and reload — do not raise body-size limits site-wide without considering the abuse surface.
Why this prompt works
The “uploads fail at exactly X megabytes” ticket is one of the most reliably misdiagnosed issues in NGINX, because the 413 it produces points at NGINX while everyone instinctively blames the backend. The fix is almost always client_max_body_size, whose default of 1m silently rejects anything larger before the backend ever sees it. This prompt names that directive first and ties it directly to the symptom, collapsing a frustrating triage loop into a one-line change.
Buffering is the subtler half. By default NGINX buffers the entire request body — to memory, then spilling to a temp file — before forwarding it, which means a 2GB upload becomes a full 2GB temp write on the proxy host and a long wait before the backend sees byte one. Surfacing proxy_request_buffering off as a deliberate choice, with its real trade-offs (no automatic retry to another upstream, and a backend that must accept a stream), lets you decide rather than discover that behavior when the temp disk fills.
The scoping guardrail is what separates a fix from a new vulnerability. It’s tempting to bump the body-size limit at the http level and move on, but that invites multi-gigabyte POSTs to every endpoint, which is a cheap denial-of-service surface. Keeping the generous limits inside the upload location — and proving the fix with a real curl -F of a large file rather than assuming — is the difference between solving the ticket and opening the next one.
Related prompts
-
NGINX 502/504 Bad Gateway Triage Prompt
Turn a wall of error.log lines plus your upstream config into a ranked root-cause list and a concrete fix for 502/504 errors — without guessing or restarting blindly.
-
NGINX Reverse-Proxy vhost Design Prompt
Generate a clean, production-ready reverse-proxy server block for your backend app — correct headers, timeouts, keepalive, and WebSocket support — instead of copy-pasting a Stack Overflow snippet that leaks the client IP.