Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PHP warns about a missing boundary and the uploaded form arrives empty

ErrorWarning: Missing boundary in multipart/form-data POST data in Unknown on line 0

Short answer

PHP could not find boundary=... in the Content-Type request header, so it cannot split the body into fields and files. The header was almost always written by hand. Delete it from your fetch, XMLHttpRequest, jQuery or cURL call and let the client add multipart/form-data together with a boundary.

  • Applies to PHP 8.3, Current Chrome and Firefox, jQuery 3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the Content-Type request header of the failing request in the browser's Network tab, or in your client's debug output. A good one reads multipart/form-data; boundary=something. Then send a request that is known to be good, and see whether PHP accepts it.

    curl -i -F "name=test" -F "photo=@/tmp/small.png" https://example.com/upload.php
  2. 2Match what you see, then jump to its fix

    1. 1The request header says multipart/form-data with nothing after it, and the code has a headers object with a Content-Type entry.fetch or XMLHttpRequest sets Content-Type to multipart/form-data by handFix
    2. 2The $.ajax options contain a contentType string with multipart/form-data in it, next to a FormData object.jQuery.ajax is given contentType: 'multipart/form-data'Fix
    3. 3A PHP script that posts to another PHP endpoint with curl_setopt sets CURLOPT_HTTPHEADER to a multipart content type.A PHP cURL script sends its own multipart headerFix
    4. 4The same warning from a test tool, a script or an HTTP library that builds its own multipart request.Another client writes the header or the body without a boundaryFix

What does the error look like?

  • Warning: Missing boundary in multipart/form-data POST data in Unknown on line 0
  • $_POST and $_FILES are empty after a form or FormData upload

Cause 1 of 4

fetch or XMLHttpRequest sets Content-Type to multipart/form-data by hand

1Check

The browser adds the boundary expression itself when it sends a FormData body. MDN warns that setting the header by hand prevents that. Search the front-end code for the line.

grep -rn "multipart/form-data" src/ public/ --include=*.js --include=*.ts --include=*.vue --include=*.jsx

2Fix

Delete the Content-Type header and pass the FormData object as the body. The browser then sends the header with a boundary.

const data = new FormData(form);
await fetch('/upload.php', {
  method: 'POST',
  body: data,            // no headers: { 'Content-Type': ... }
});

3Verify

The request in the Network tab now shows a boundary in its Content-Type header, and the PHP warning stops.

var_dump($_POST, $_FILES);

Confirmed by developer.mozilla.org

Did this fix it?

Cause 2 of 4

jQuery.ajax is given contentType: 'multipart/form-data'

1Check

jQuery sends the contentType string exactly as written, and unless told otherwise it also turns an object in data into a query string. A typed multipart value has no boundary. Look at the options of the call.

grep -rn "contentType" assets/ resources/js/ public/ --include=*.js

2Fix

Set contentType to false, so jQuery sends no content type header of its own, and processData to false, so the FormData is left alone. The browser then writes the header with the boundary.

$.ajax({
  url: '/upload.php',
  method: 'POST',
  data: new FormData(form),
  contentType: false,   // let the browser write the header and the boundary
  processData: false,   // do not turn the data into a query string
});

3Verify

A fresh upload fills $_POST and $_FILES and the warning is gone.

var_dump($_POST, $_FILES);

Confirmed by api.jquery.com

Did this fix it?

Cause 3 of 4

A PHP cURL script sends its own multipart header

1Check

PHP's cURL picks the content type from the type of CURLOPT_POSTFIELDS: an array is sent as multipart/form-data, a URL-encoded string as application/x-www-form-urlencoded. A multipart header typed by hand has no boundary in it.

grep -rn "CURLOPT_HTTPHEADER\|CURLOPT_POSTFIELDS" app/ src/ lib/ 2>/dev/null

2Fix

Pass an array to CURLOPT_POSTFIELDS, use CURLFile for files, and drop the Content-Type header from the header list.

$ch = curl_init('https://example.com/upload.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'name' => 'test',
    'photo' => new CURLFile('/tmp/small.png'),
]);
curl_exec($ch);

3Verify

The receiving script sees both the field and the file.

var_dump($_POST, $_FILES);

Confirmed by php.net

Did this fix it?

Cause 4 of 4

Another client writes the header or the body without a boundary

1Check

PHP's parser looks for the word boundary in the header and an equals sign after it. RFC 7578 makes the parameter required, and the same value must delimit the parts in the body.

curl -v -F "a=1" https://example.com/upload.php 2>&1 | grep -i "content-type"

2Fix

Remove the hand-written header and let the tool build the request. If you have to build the body yourself, the header must read multipart/form-data; boundary=<value>, with a value that appears in the body as the part delimiter.

Content-Type: multipart/form-data; boundary=----example7d4a3c
(the body parts are separated by --example7d4a3c lines in the same body)

3Verify

Send the request again and check that the field arrives.

var_dump($_POST, $_FILES);

Confirmed by rfc-editor.org

Did this fix it?

How do I stop it coming back?

  • Never write a Content-Type header for a FormData body; leave it to the browser.
  • Add one upload test, with a small file, to your test suite or deploy check.
  • Log the Content-Type of failed uploads on the server, so the cause shows in the log instead of a guess.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Apache returns 403 when a URL contains %3F

a request like /page%3Fname=test is refused while /page?name=test works

Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.