FormData Upload Errors: Check the Multipart Boundary

A browser FormData upload can fail because a request wrapper sets the wrong Content-Type header. When the browser constructs a multipart body, it also needs to supply the matching boundary parameter. Setting only multipart/form-data yourself can leave the server unable to separate the parts correctly.

MDN's FormData guide explicitly warns against manually setting that header for this workflow. This guide focuses on a narrow parsing problem. It does not replace file-type checks, authorization, upload limits, or other server-side safeguards.

Start with a minimal request

Use an approved small test file and the actual field name expected by the server. A minimal browser example is:

const data = new FormData();
data.append('file', fileInput.files[0]);

const response = await fetch('/upload', {
  method: 'POST',
  body: data
});

The fileInput variable must refer to your real file input, and production code should check that a file exists and handle errors. The example deliberately omits a manually supplied Content-Type. Add authentication through the application's approved mechanism without exposing credentials in shared diagnostics.

Inspect wrapper defaults

An API helper designed for JSON may automatically add Content-Type: application/json and stringify the body. That behavior is appropriate for some requests but wrong for a FormData body. Check the actual request produced after the wrapper runs.

Create an explicit body-type branch in the supported request-building layer. Do not merely change a call site's header if the wrapper later overwrites it. Also avoid manually constructing a multipart body unless there is a specific, well-reviewed need; correct framing involves more than joining field values.

Test the minimal request without unrelated application layers in a controlled development environment. If it works, add the wrapper back and compare the produced request metadata. That narrows the problem without changing every server setting at once.

Verify field names and values

The server may expect file, document, or another exact key. A correct multipart boundary will not fix a mismatched field name. Check whether the endpoint expects one file or multiple files and how additional form fields are named.

If using new FormData(form), inspect which controls are included. Disabled controls and unnamed fields can behave differently from visible enabled controls with names. A file input shown on screen is not proof that the resulting body contains the expected part.

Avoid putting sensitive test data into a public issue. A useful report can state the field names, small synthetic filename, body type, and observed error without including a customer's document or authentication token.

Separate parsing from validation

First determine whether the server parsed the multipart structure and found the intended part. Then determine whether it accepted the file's size, type, content, and authorization. These are different stages and should produce distinguishable diagnostics.

For example, a missing part, an oversized file, and a rejected document type should not all lead to the same vague “upload failed” message in internal logs. Customer-facing messages can remain concise while the server records a safe error category.

Do not weaken validation to make a parsing test pass. If a tiny permitted test file works but a larger real file fails, investigate configured limits and the actual content rather than immediately allowing every type or unlimited size.

Check intermediaries without assuming blame

Compare the request at the browser and the server boundary using approved diagnostics. A reverse proxy, application gateway, or framework body parser may impose limits or route the request differently. Record the relevant component and version.

Do not claim that a proxy stripped the boundary without observing evidence. A JSON-oriented client wrapper is often easier to inspect first. If the request metadata is correct at the browser but differs at the server, investigate the specific intervening hop.

Keep production logging bounded. Capturing entire multipart bodies can expose files, form data, and secrets. Prefer request IDs, parsing stage, safe field presence, size observations, and redacted header information.

Build a regression test set

Test one small permitted file, no selected file, an unexpected field name, an oversized file, and a disallowed type. Include the actual request wrapper so the suite catches a future JSON-default regression.

Verify that repeated clicks or network retries do not create unintended duplicate uploads. If uploading creates consequential records, use the application's supported idempotency design. The transport parsing fix should not hide a separate duplicate-write problem.

After deployment, test through the real application path and confirm the saved record or file metadata. A successful HTTP status alone does not prove the correct file was stored. Our file upload validation guide covers the broader safety boundary.

JSON Diff can compare redacted error responses or configuration manifests. It cannot inspect multipart framing or upload a file. Use the browser's network view and approved server diagnostics for those checks.

Conclusion

For browser FormData requests, let the browser supply the matching multipart boundary. Check wrappers and field names, then distinguish parsing, validation, and storage outcomes. A narrow verified fix is more reliable than replacing one upload error with broader server permissions or limits.