413 Payload Too Large
Why an upload or request returns 413 Payload Too Large, which layer's size limit is actually responsible, and how to raise it or shrink the payload.
Last updated
413 Payload Too Large (nginx shows: "413 Request Entity Too Large"; Express/body-parser shows: "PayloadTooLargeError: request entity too large")
What it means: The server rejected the request because its body — an upload, a JSON payload, a form submission — exceeds a size limit enforced somewhere in the stack; the exact wording differs by server, but status code 413 is consistent.
Likely causes
Most probable first — with how to confirm.
- 1.A reverse proxy in front of your app (nginx, Apache, a CDN or load balancer) has its own body-size limit smaller than your app's — nginx defaults to 1MB via `client_max_body_size`, a very common trip point for uploads.
- 2.Your framework's own body parser has a size limit smaller than the payload. Express's `express.json()` defaults to just 100kb — far tighter than nginx's 1MB — so for JSON it is usually the app, not the proxy, doing the rejecting.
- 3.The client is genuinely sending more data than intended — an unoptimized image upload, a base64-encoded file (which inflates size by roughly a third), or an accidental duplicate payload.
- 4.A CDN or serverless hosting platform enforces a hard request-size ceiling that app-level configuration can't override.
Fixes
Safest first; destructive ones are called out.
- →Raise the limit closest to where the rejection actually happens — check the proxy first (nginx: `client_max_body_size 20M;`), then the framework's body-parser limit (Express: `express.json({ limit: '20mb' })`), since one low limit anywhere in the chain still produces a 413.
- →Reduce the payload instead: compress or resize images client-side before upload, or send binary data rather than base64, which shrinks the same file by roughly a quarter.
- →For genuinely large files, switch to a streamed or chunked upload, or a direct-to-storage upload via a signed URL, instead of pushing the whole file through your app server's request body.
- →On a serverless or managed platform, check its documented hard request-size cap — some won't let you raise it past a fixed ceiling regardless of app config.
Part by part
- 413
- The HTTP status for a request body the server declined to process because of its size. The response is the server refusing, not the upload failing.
- 413 Request Entity Too Large
- nginx's wording, from the older RFC. Seeing this phrasing tells you the reverse proxy rejected it before your application saw anything.
- PayloadTooLargeError
- Express and body-parser's wording. This one means the request reached your app, so the limit that fired is in your code rather than in front of it.
Common mistakes
app.use(express.json({ limit: '50mb' }))Raising the application limit alone leaves nginx rejecting the request first, so nothing changes. The wording of the error tells you which layer refused, and both usually need adjusting.
Setting client_max_body_size in the wrong nginx blockIt is only effective in the http, server or location block that actually handles the request. Placed elsewhere it is silently ignored, which looks exactly like the setting not working.
Raising the limit until the largest known file fitsEvery increase is also an increase in what a single request can make the server buffer. Above a few megabytes, direct-to-storage uploads are the better answer than a bigger limit.
Questions
Which layer rejected my request?
The wording says. "Request Entity Too Large" as an HTML page is nginx; a JSON error mentioning PayloadTooLargeError is Express. Anything with a cloud provider's branding is the load balancer, which often cannot be raised at all.
What is Express's default limit?
100kb for both the JSON and urlencoded parsers. It is deliberately small, and it surprises people who assume the default is around a megabyte — a modest base64 image exceeds it comfortably.
How should large uploads work instead?
Have the client upload directly to object storage with a pre-signed URL, and send your server only the resulting key. The file never passes through your application, so no body limit applies and memory stays flat.
Why does the browser show a network error rather than the 413?
Some servers close the connection as soon as the limit is exceeded, before the response is fully written. The client then sees a connection reset instead of a status code, which makes a size problem look like a network one.