$_FILES key is undefined when a jQuery Ajax form posts files
Warning: Undefined array key "file" in upload.phpShort answer
With jQuery, a multipart upload needs a FormData body plus processData: false and contentType: false. Leave either out and jQuery turns the data into a query string or sets its own Content-Type, so PHP never receives the file. Also check the input has a name and the POST is under post_max_size.
Fix it fast
1Find out which cause you have
Look at the request in the browser's network tab and at what PHP actually received. The Content-Type header should read multipart/form-data with a boundary.
<?php // top of upload.php, temporary header('Content-Type: text/plain'); echo 'Content-Type: ', $_SERVER['CONTENT_TYPE'] ?? '(none)', "\n"; print_r($_POST); print_r($_FILES);2Match what you see, then jump to its fix
- 1
PHP sees a Content-Type of application/x-www-form-urlencodedjQuery serialises the FormData because processData is left onFix - 2
The body is multipart but PHP reads no fields, or the Content-Type has no boundarycontentType is not false, so jQuery overwrites the multipart headerFix - 3
FormData is sent correctly but $_FILES has no entry for your keyThe file input has no name, or the field is disabledFix - 4
$_POST and $_FILES are both empty even though the request looks right in the network tabThe request is bigger than post_max_sizeFix
- 1
What does the error look like?
Warning: Undefined array key "file" in upload.phpNotice: Undefined index: file$_FILES is empty after $.ajax with data: new FormData(form)The network tab shows Content-Type: application/x-www-form-urlencoded for a request that should be multipart
Cause 1 of 4
jQuery serialises the FormData because processData is left on
1Check
processData defaults to true, so jQuery converts an object passed as data into a query string. A FormData object must not be converted.
$.ajax({ url: 'upload.php', type: 'POST', data: new FormData(form) }); // missing processData: false2Fix
Set processData to false so jQuery sends the FormData untouched.
$.ajax({
url: 'upload.php',
type: 'POST',
data: new FormData(form),
processData: false,
contentType: false
});3Verify
The network tab now shows Content-Type: multipart/form-data with a boundary, and $_FILES has the entry.
print_r($_FILES);Confirmed by api.jquery.com
Cause 2 of 4
contentType is not false, so jQuery overwrites the multipart header
1Check
The default contentType is application/x-www-form-urlencoded; charset=UTF-8, and a type you set yourself is always sent. The browser must set multipart/form-data with its own boundary, so do not set a header by hand either.
// look for these in the call and in $.ajaxSetup()
contentType: 'multipart/form-data'
headers: { 'Content-Type': 'multipart/form-data' }2Fix
Pass contentType: false, which tells jQuery to send no Content-Type header, and remove any hand-written multipart header.
contentType: false,
processData: false3Verify
Repeat the upload; PHP shows the multipart Content-Type and a filled $_FILES.
print_r($_SERVER['CONTENT_TYPE']);Confirmed by api.jquery.com
Cause 3 of 4
The file input has no name, or the field is disabled
1Check
new FormData(form) only collects inputs that have a name attribute, and it skips disabled fields. The name is also the key PHP uses in $_FILES.
document.querySelectorAll('#myform input[type=file]').forEach(i => console.log(i.name, i.disabled));2Fix
Give the input a name, enable it, and read that same key in PHP. For a file that is not in the form, append it by hand.
<input type="file" name="userfile">
const fd = new FormData(form);
fd.append('extra', fileInput.files[0]);3Verify
Log the FormData entries before sending.
for (const [k, v] of new FormData(form)) console.log(k, v);Confirmed by developer.mozilla.org
Cause 4 of 4
The request is bigger than post_max_size
1Check
When the body exceeds post_max_size (default 8M), PHP leaves $_POST and $_FILES empty.
<?php
echo $_SERVER['CONTENT_LENGTH'] ?? 0, ' / ', ini_get('post_max_size');2Fix
Raise post_max_size above upload_max_filesize in php.ini and reload PHP.
; php.ini
upload_max_filesize = 64M
post_max_size = 72M3Verify
Upload the same file again.
print_r($_FILES);Confirmed by php.net
How do I stop it coming back?
- Guard the read: check isset($_FILES['userfile']) and its error value before using it.
- Never set a multipart Content-Type by hand on an Ajax request that sends FormData.
- Return a JSON error when $_FILES is empty on a POST, so the front end can show a message.
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
A PHP upload fails or $_FILES comes back empty
$_POST and $_FILES are both empty on a large upload
A PHP upload fails for one of four reasons: the temporary directory is not writable, the whole POST is bigger than post_max_size, one file is bigger than upload_max_filesize, or there are more files than max_file_uploads.
4 causes, each with a fixBack end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack 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 fixBack end
Apache returns 500 with Premature end of script headers
500 Internal Server Error
Apache ran your script, but the script printed no valid HTTP header before its output.
3 causes, each with a fixBack end
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fixBack end
AWS SDK for PHP cannot get credentials from the instance profile metadata server
Error retrieving credentials from the instance profile metadata server.
The SDK tries the EC2 instance metadata service when it has no valid credentials from anywhere earlier in its chain.
4 causes, each with a fix