When a file upload fails, the visible browser message rarely identifies the real cause. This guide explains 413, 422, 408, 499, timeout, and multipart boundary errors, then gives you a repeatable workflow for tracing failures across the browser, JavaScript client, reverse proxy, application server, and object storage.
Overview
A file upload is not handled by one component. The browser creates a request, a proxy may inspect or limit it, the application server parses the request and validates the file, and storage may impose another size, time, or permission constraint. A failure at any layer can look like a generic “upload failed” message in the interface.
Start by separating transport failures from application failures. A transport failure means the request was rejected, interrupted, or never completed. An application failure means the server received enough of the request to process it but rejected its contents or state. The HTTP status is an important clue, but it must be read alongside request size, headers, timing, server logs, and the point at which the request stopped.
For a broader method of reading response codes, see HTTP Status Codes and API Errors: Diagnose Failed Requests. Upload investigations benefit from the same discipline: reproduce the request, record the evidence, change one variable, and test again.
| Symptom or response | Likely cause | First check |
|---|---|---|
| 413 Payload Too Large | A proxy, web server, application, or storage service rejected the request size. | Compare the file and complete request size with limits at every layer. |
| 422 Unprocessable Content | The request was parsed, but validation failed. | Inspect field names, required metadata, MIME rules, file contents, and the response body. |
| 408 Request Timeout | The server did not receive the request in the expected time window. | Check upload speed, client inactivity, server timeouts, and proxy read or request settings. |
| 499 Client Closed Request | A proxy recorded that the client disconnected before completion; this is commonly a proxy-specific log status. | Compare client cancellation, navigation, network loss, and upstream processing time. |
| Multipart boundary error | The multipart body and Content-Type boundary do not match, or the body was not encoded as multipart. | Inspect the Content-Type header and let the browser create it when using FormData. |
| Connection reset or generic network error | The connection ended before a useful HTTP response, often because of a proxy, timeout, network, or server crash. | Check proxy and application logs, request duration, and whether the request reached the origin. |
What to track
Request construction
For an HTML form, confirm that the form uses method="post" and enctype="multipart/form-data". The input name must match the field name expected by the server. A correct file selected in the browser can still arrive under the wrong key, particularly when the frontend and backend were changed separately.
With JavaScript, use FormData for a multipart upload and avoid manually setting the Content-Type header in a browser request. The browser adds the boundary parameter that connects the header to the multipart body. A pattern such as fetch(url, { method: 'POST', body: formData }) allows the browser to generate the appropriate header. Manually sending Content-Type: multipart/form-data without its boundary is a common cause of “missing boundary” or “invalid multipart” errors.
Also record whether the client is sending the original file, a transformed copy, or a base64-encoded string. Base64 increases the amount of data compared with the binary file, so a request that appears to fit a file-size limit may exceed a limit after encoding. If JSON is used instead of multipart data, validate the payload structure separately; the JSON validation and formatting guide can help isolate malformed request data.
Size, headers, and timing
Track at least the file size, total request size, request method, URL, status code, response body, upload duration, and whether the request included an Expect, Content-Length, or Transfer-Encoding header. Do not assume the file size equals the request size: multipart field names, boundaries, metadata, and other form fields add overhead.
Compare the browser’s network record with a controlled command-line request. A minimal example is:
curl -v -F "file=@./sample.bin" https://example.test/upload
Use a non-sensitive test file and a safe environment. The verbose output can show whether a redirect, TLS issue, proxy response, or server response occurs before the application receives the upload.
Limits at each layer
Maintain a small configuration checklist for the complete path:
- Browser or client: maximum selectable file size, cancellation behavior, retry logic, and offline or unstable-network handling.
- Reverse proxy or load balancer: maximum request body size, request header limits, idle timeout, request timeout, buffering, and upload buffering location.
- Web server and application framework: body-parser or multipart limits, per-route limits, temporary directory capacity, execution timeouts, and file validation rules.
- Object storage: single-request limits, multipart-upload rules, presigned URL expiration, permissions, and the allowed content type.
- Observability: request ID, status code, duration, received byte count, rejected byte count, and the layer that produced the response.
Do not log file contents or credentials while diagnosing an upload. Log metadata and correlation identifiers instead. A request ID passed from the edge to the application makes it much easier to match a browser failure with proxy and server records.
Cadence and checkpoints
Use a lightweight upload check whenever an endpoint is deployed, a proxy configuration changes, a framework is upgraded, or storage settings are modified. A useful regression set includes a tiny valid file, a file near the documented limit, a file just above that limit, an unsupported type, an empty file if it should be rejected, and a deliberately interrupted upload.
On a monthly or quarterly cadence, review the following:
- Success rate by size range: separate small, medium, and large uploads instead of relying on one overall percentage.
- Failure status distribution: watch for new 413, 422, timeout, cancellation, and generic network-error patterns.
- Duration percentiles: compare upload time and post-upload processing time. A file may upload successfully but time out while the server scans, transforms, or stores it.
- Layer agreement: confirm that proxy logs, application logs, and storage logs report the same request outcome.
- Configuration drift: compare documented limits and timeouts with deployed values in each environment.
Keep a small test matrix in version control. It should identify the environment, endpoint, test file, expected status, maximum duration, and expected validation message. This turns a one-off debugging task into a repeatable developer workflow. If uploads are part of an API contract, document the multipart field and constraints in the OpenAPI definition and review them with the OpenAPI validation guide.
How to interpret changes
A sudden increase in 413 responses usually points to a changed limit, larger real-world files, or a request format that adds unexpected overhead. Identify which layer returns the response: an edge-generated error may have different headers and body wording from an application-generated one. If small files pass but large files fail at a consistent threshold, compare that threshold with every configured body limit.
A 422 response is different from a size rejection. It generally indicates that parsing completed and validation failed. Check whether the backend expects a field called file while the client sends upload, whether a required title or identifier is missing, and whether the server validates the file’s detected content rather than its extension. Preserve the response’s structured error details where safe; replacing every validation error with “upload failed” makes future diagnosis slower.
Timeouts require timing evidence. If the connection fails while bytes are still being sent, investigate client, proxy, and upload-read timeouts. If the upload completes but the response arrives too late, investigate application processing, antivirus or document inspection, image conversion, and storage calls. A 499 in a proxy log often means the browser, mobile client, or an upstream caller gave up first; it does not by itself prove that the origin was healthy or unhealthy.
For multipart boundary failures, inspect the raw request headers and the client code. The header should contain a boundary parameter that corresponds to separators in the body. Do not copy a boundary from one request into another, and do not treat a multipart body as JSON. If a library constructs the request, verify that another middleware or wrapper has not replaced the body or header.
When a change affects only one environment, compare the complete route rather than just the application code. Differences in ingress annotations, web-server configuration, temporary storage, TLS termination, DNS routing, and object-storage credentials can all produce an apparently application-level failure.
When to revisit
Revisit this guide after any upload endpoint deployment, reverse-proxy or load-balancer change, application framework upgrade, storage migration, validation-rule change, or frontend rewrite. Review it sooner when users report that only large files fail, uploads stop on slower connections, a new browser or mobile client behaves differently, or error rates change without an obvious code release.
For a practical incident checklist, begin with one failing request and record its file size, complete request size, status, duration, response body, request ID, and environment. Reproduce it with a minimal file and a command-line request, then test each boundary in order: client, proxy, application parser, validation, and storage. Change one setting at a time and record the result.
Finally, turn the discovered limit into an explicit contract. Document the accepted field name, maximum file and request sizes, supported types, timeout expectations, validation errors, retry behavior, and whether resumable or direct-to-storage uploads are supported. Re-run the version-controlled test matrix at least monthly or quarterly, and whenever a recurring metric moves. That habit keeps file upload troubleshooting from becoming a production-only surprise.
For related operational workflows, see the guides on transferring large build artifacts and moving Docker images between environments.