Why my file upload fails — error 413 and the three causes that catch everyone

File upload is the part of a project that breaks most quietly. Locally everything flies; on the server the user hits "Upload," the spinner spins — and you get either a 413 or nothing at all.
Let me start with the fact that saves an hour of debugging: a 4 MB file can fail to fit under a 4.5 MB limit. That's not mysticism or a broken host — let's find where the difference goes.
The symptom: 413 and its disguises
The canonical form is 413 Payload Too Large, "request body too big." But you won't always see it that way — different layers have different manners.
- A plain
413in the browser console — lucky you, diagnosis done. FUNCTION_PAYLOAD_TOO_LARGE— the same thing on serverless hosting.- The request dies with no response, console says "network error" — the server hung up mid-sentence.
- Silence: the request returned
200and there's no file — that's cause three, the file never travelled.
If the codes themselves are fuzzy, see HTTP status codes.
Cause 1: the body size limit — and there's more than one
The core misunderstanding: people hunt for "the" limit, but there are several along the path, and the smallest one wins. The request runs a gauntlet, and any link can cut it off:
| Where the limit lives | Typical default | |-----------------------|-----------------| | nginx in front of the app | 1 MB | | JSON parsing in Express | 100 KB | | Serverless functions | ~4.5 MB, cannot be raised | | Next.js Server Actions | 1 MB |
Hence the classic: "but I set 50 MB in my app config, why a 413?" — because the request never reached your app; nginx cut it at its one megabyte.
How to fix. Work out who's complaining: if the response is an HTML page with a web server's name on it, that's nginx, and the limit lives in its config (client_max_body_size). If the response came from your own code, change the framework setting. Serverless functions, though, have a hard ceiling that doesn't move at all — those need a different approach, covered at the end.
Cause 2: you're sending the image as a string
And here's the answer to "4 MB didn't fit in 4.5 MB."
Plenty of tutorials suggest reading the file in the browser and sending it inside JSON as a base64 string — convenient, one tidy object. But base64 writes binary data using letters, and the size grows by roughly a third. A 4 MB file becomes 5.4 MB on the wire. On top of that sits the JSON body limit, which is far stricter than any file limit.
How to fix: don't encode the file as text. Send it as-is via FormData, so it travels as a binary block with no markup:
const data = new FormData();
data.append('file', input.files[0]);
await fetch('/api/upload', { method: 'POST', body: data });
Cause 3: the file never left at all
No error, but nothing on the server? The request went out empty. Three culprits, most common first:
You set the header by hand. The most maddening one. You must not add Content-Type to a FormData request yourself:
// broken: the boundary between parts is lost, the server can't parse it
fetch(url, { method: 'POST', body: data, headers: { 'Content-Type': 'multipart/form-data' } });
The browser sets that header itself, together with a random separator string. Writing it manually erases the separator — and the server sees mush instead of a file. Just don't touch the header.
The field has no name. A file input needs a name attribute — that's how the server finds the file. Without it the field goes nowhere.
A plain form without the right enctype. If you submit with a classic HTML form rather than code, it needs enctype="multipart/form-data", or the browser sends only the filename, not the contents.
The right path: don't route files through your server
Everything above treats symptoms. But once files exceed a couple of megabytes, the correct answer is not to pass them through your app at all.
The pattern: your server hands the browser a temporary link that uploads straight into storage, the browser sends the file there directly, and you get back a finished URL to save in the database. Your code only ever touches that one string.
The upside is obvious: body size limits stop existing as a category, your server isn't busy shovelling bytes, and your host doesn't bill you for the round trip. This path is walked step by step in how to add image upload.
It works locally but 413s in production — why?
Because locally there's nothing in front of your app. On the server the request first crosses a web server or a platform, each with its own one-megabyte defaults. You changed the app's settings while a layer above does the cutting. It's a special case of a bigger topic — why your app works locally but not in production.
How do I tell whose limit it is?
Look at the response body, not just the code. An HTML page naming a web server — that's the web server. JSON in your app's own shape — your framework. A platform's name in the error text — the host's ceiling. And test the size directly: send a 100 KB file. If it goes through, size is the issue; if it doesn't, your form is.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





