Maaz Zindani

Loading the index…

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

$_FILES key is undefined when a jQuery Ajax form posts files

ErrorWarning: Undefined array key "file" in upload.php

Short 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.

  • Applies to jQuery 3.7, PHP 8.3, modern browsers
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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);
  2. 2Match what you see, then jump to its fix

    1. 1PHP sees a Content-Type of application/x-www-form-urlencodedjQuery serialises the FormData because processData is left onFix
    2. 2The 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. 3FormData is sent correctly but $_FILES has no entry for your keyThe file input has no name, or the field is disabledFix
    4. 4$_POST and $_FILES are both empty even though the request looks right in the network tabThe request is bigger than post_max_sizeFix

What does the error look like?

  • Warning: Undefined array key "file" in upload.php
  • Notice: 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: false

2Fix

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

Did this fix it?

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: false

3Verify

Repeat the upload; PHP shows the multipart Content-Type and a filled $_FILES.

print_r($_SERVER['CONTENT_TYPE']);

Confirmed by api.jquery.com

Did this fix it?

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

Did this fix it?

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 = 72M

3Verify

Upload the same file again.

print_r($_FILES);

Confirmed by php.net

Did this fix it?

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 fix

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.