Multipart Form Data Explained: Debugging File Upload Requests in the Browser

Overview

A multipart/form-data request divides the request body into separate parts. Each part has headers, such as a field name and, for a file, a filename and content type. A typical upload might contain a text field called userId and a file field called document. The server must parse every part and map it to the names expected by the upload API.

The key detail is the multipart boundary. The boundary is a delimiter generated for a particular request and placed in both the Content-Type header and the body. It tells the server where one part ends and the next begins. If a client manually sets an incomplete or mismatched boundary, the server may report that the body is malformed or behave as if no file was sent.

When debugging, inspect the request in layers rather than changing several things at once:

1. Confirm that the browser or client selected the intended file.
2. Confirm that the request uses the expected HTTP method and URL.
3. Inspect the form field names and multipart headers.
4. Compare the request with the server’s upload contract.
5. Check the response, server logs, size limits, and parsing errors.

For related checks involving file size, MIME types, and security controls, see How to Test File Uploads Online: Size Limits, MIME Types, and Security Checks.

Checklist by scenario

When the request contains no file

• Inspect the page’s file input and confirm it has a name attribute, such as name="document".
• Confirm the JavaScript reads the correct input element and does not submit an empty FileList.
• Check that the request is built with FormData, for example formData.append('document', file).
• Verify that the field name matches the server parameter exactly. document, file, and upload are different names.
• Make sure the selected file has not been removed or replaced before the request is sent.

In browser developer tools, open the Network panel, submit the form, and select the upload request. Look under Payload or Request for the form-data parts. Browser labels vary, but you should be able to see the file field and its filename. If only text fields appear, the problem is usually in file selection, field naming, or request construction rather than server storage.

When the server reports a boundary or malformed-body error

• Inspect the complete Content-Type request header.
• Confirm it includes multipart/form-data and a boundary parameter generated for that request.
• Do not hard-code Content-Type: multipart/form-data when sending browser FormData.
• Remove middleware or proxy transformations that may rewrite the body or header.
• Compare the raw request shape with a known-good request from an API client or curl.

With browser fetch, the safe pattern is to pass the FormData object as the body and allow the browser to set the content type. Manually setting the header can prevent the browser from adding the correct boundary. The same principle applies to many HTTP client libraries: use their multipart helper instead of assembling the body as a plain string.

When testing with curl

Use the -F option to create a multipart request:

curl -X POST https://example.test/api/upload \
  -F "document=@./report.pdf" \
  -F "description=Quarterly report"

The @ tells curl to read a local file. To provide a deliberate content type for a file part, use a form value such as:

curl -X POST https://example.test/api/upload \
  -F "document=@./report.pdf;type=application/pdf"

Use verbose output when you need to inspect the request and response exchange:

curl -v -X POST https://example.test/api/upload \
  -F "document=@./report.pdf"

Avoid replacing -F with -d or manually copying a multipart body unless you are specifically testing a low-level parser. Those options produce a different request format and can make a valid upload API appear broken.

When an API client succeeds but the browser fails

• Export the working request from the API client as curl, then compare its URL, method, field names, and headers with the browser request.
• Check browser-only headers, including authentication, CSRF protection, and origin-related requirements.
• Confirm that the browser sends credentials when the API requires them.
• Check whether a reverse proxy or development server routes the browser request to a different endpoint.
• Compare the actual file size and filename, not only the visible form label.

A working API-client request proves that one request shape is accepted; it does not prove that the browser is sending the same shape. Treat the two requests as separate test cases.

When multiple files or repeated fields are involved

Check whether the server expects repeated fields such as files[], several parts with the same name, or a JSON field containing metadata. Confirm the order if the API associates each file with a corresponding value. Test one file first, then add files incrementally. For a broader implementation checklist, see How to Build a Multi-File Upload Flow With Ordering, Removal, and Retry.

What to double-check

Request construction

Verify the HTTP method, endpoint path, query parameters, authentication, and any required anti-forgery token. Confirm that the frontend does not serialize FormData into JSON. If the request body is shown as a string such as [object FormData], the client code is not passing the object correctly.

Field names and metadata

Check the exact spelling and casing of every field. A file’s filename, browser-reported MIME type, and actual content can be different. Treat the client-provided content type as a useful hint, not as the only validation signal. The server should apply its own file type, size, and content checks appropriate to the application.

Limits and failure locations

Identify where the failure occurs: browser validation, proxy, web server, application framework, object storage, or post-upload processing. A request that reaches the application may still fail later because of a body-size limit, timeout, storage rule, filename handling, or antivirus or transformation step. Record the HTTP status, response body, request identifier, and relevant server log entry.

Privacy and sensitive test files

Use non-sensitive test files whenever possible. Images and documents may contain metadata that is not visible in the main content. Review EXIF, Metadata, and Privacy: What to Strip From Uploaded Files before using real files in external testing tools or shared environments.

Common mistakes

• Manually setting the multipart header: The header may lack the boundary that matches the generated body. Let the browser or multipart library create it.
• Using the wrong field name: A server expecting avatar will not necessarily treat a field named file as the upload.
• Sending JSON by accident: A JSON request can carry a URL or encoded data, but it is not the same as a multipart file part.
• Testing only a tiny file: A small sample may pass while realistic files expose request-size, timeout, or processing limits.
• Trusting the file extension: The extension alone does not establish what a file contains. Validate uploads on the server.
• Debugging only the frontend: A correct request can still be rejected by routing, authentication, parsing, storage, or downstream processing.
• Logging sensitive bodies: Request bodies can contain personal or confidential content. Prefer safe metadata, identifiers, and redacted diagnostics.

For controls beyond request formatting, consult How to Prevent File Upload Abuse: Rate Limits, Quotas, and Type Restrictions and Signed Upload URLs vs Proxy Uploads.

When to revisit

Return to this checklist whenever the upload workflow, frontend framework, API client, proxy, storage provider, or server parser changes. Recheck it before a seasonal planning cycle or any release that changes file types, maximum sizes, authentication, multi-file behavior, or upload destinations. Browser updates and infrastructure changes can also expose assumptions that were previously hidden.

Keep one small, repeatable test matrix with a valid file, an empty selection, an unsupported type, a large file, a filename containing spaces, and—where relevant—multiple files. For each case, record the expected status, response shape, and storage result. When a failure appears, capture the browser request, reproduce it with curl, and compare the two requests one property at a time. This turns multipart debugging from trial and error into a short, documented verification process.

Finally, review the workflow after changing retention or temporary storage behavior. Upload handling includes more than accepting the request; cleanup, access control, and error recovery should remain part of the test plan. See Temporary File Storage for Upload Workflows for that follow-up checklist.