Upload Limit Preflight

Why nothing appears in your logs

Local development has no request-body limit worth noticing. Serverless platforms enforce one — commonly around 4.5MB — at the edge, before your function is invoked. So:

• your handler never executes, so your error handling never runs
• the response is the platform's: usually a bare 413 with an HTML body
• your client, expecting JSON, fails to parse it and shows "something went wrong"
• nothing in your logs mentions an upload, because nothing of yours was called

The user learns that photos "sometimes don't work". You learn nothing, because from your application's point of view the request never happened.

The trap inside the trap

The limit applies to the encoded body, not the file. Base64 inflates by about a third, so a 3.5MB image sent as a JSON data URL is ~4.7MB — over a 4.5MB limit while the file plainly is not. Multipart adds boundaries and per-part headers on top.

So if (file.size > LIMIT) passes files that will be rejected, and rejects them in the one way you cannot observe. checkUpload measures what the platform measures, and when the file alone would have fitted it says so explicitly rather than reporting a generic "too large".

The number you show the user must be the file limit

Telling someone "max 4.5MB" when you base64-encode is wrong by a third. They choose a file that matches the number you gave them, it fails, and they reasonably conclude the upload is broken rather than the file too large.

maxFileBytes returns the largest file that fits for a given encoding, and there is a round-trip test asserting the advertised maximum actually passes the check — because a stated limit that its own validator rejects is worse than no limit at all.

Sometimes the answer is not a bigger limit

shouldUseDirectUpload flags anything past half the limit. Beyond that size the fix is a presigned upload straight to object storage, with the request never touching your function.

Routing large files through a serverless function also costs invocation time proportional to file size — paid on every upload, invisible until the bill.

What this does NOT do

No uploading, no storage, no presigning, no image processing. It answers "will this request survive" before you send it.

It does not validate file contents. A content-type allowlist checks what the client declared, and a client can declare anything — an executable renamed .png passes. Real validation means inspecting magic bytes server-side, after the upload, and this deliberately does not pretend to do that.

The platform limit is a value you supply. Providers change theirs, and a stale constant is exactly the silent failure this exists to prevent — so check yours rather than trusting a number in a package.

Verified

15 tests: base64 and multipart overhead, the file-fits-but-request-does-not case flagged explicitly, other form fields counted, the advertised maximum round-tripping through the check for all three encodings, never returning a negative maximum, content-type allowlisting including parameters after the media type, missing content type refused rather than allowed, empty files flagged, and the direct-upload threshold.

Not covered: no test against a real platform, so the limit constant is whatever you pass in.