Maaz Zindani

Loading the index…

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

A PHP upload fails or $_FILES comes back empty

Error$_FILES is an empty array after a POST with a file

Short answer

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. Print the error value PHP stores for the file, then check the four settings in the order below.

  • Applies to PHP 8.3, PHP 8.4, Ubuntu 24.04, PHP-FPM
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Show the settings PHP really uses (the web server can load a different php.ini than the terminal) and the error code PHP recorded for the file.

    <?php
    // temporary debug page, delete after use
    foreach (['file_uploads','upload_tmp_dir','upload_max_filesize','post_max_size','max_file_uploads','open_basedir'] as $k) {
        echo $k, ' = ', var_export(ini_get($k), true), "\n";
    }
    echo 'tmp dir in use: ', sys_get_temp_dir(), "\n";
    var_dump($_FILES);
  2. 2Match what you see, then jump to its fix

    1. 1$_FILES holds the file name but the move fails, or upload_tmp_dir shows a path that does not existThe temporary directory is missing, not writable, or blocked by open_basedirFix
    2. 2Both $_POST and $_FILES are empty, with no error code to readThe whole request is bigger than post_max_sizeFix
    3. 3The file entry exists in $_FILES but its error value is not UPLOAD_ERR_OKOne file is bigger than upload_max_filesizeFix
    4. 4A multi-file form returns only the first 20 filesMore files than max_file_uploads in one requestFix

What does the error look like?

  • $_FILES is an empty array after a POST with a file
  • $_POST and $_FILES are both empty on a large upload
  • move_uploaded_file() returns false
  • Setting upload_tmp_dir in .htaccess or .user.ini has no effect

Cause 1 of 4

The temporary directory is missing, not writable, or blocked by open_basedir

1Check

upload_tmp_dir must be writable by the user PHP runs as. If it is unset, PHP uses the system temp directory, and if the configured one is not writable PHP falls back to that. With open_basedir enabled, the system temp directory has to be allowed too.

# the PHP user is set by the pool file (user = ...), often www-data
ls -ld /var/tmp/php-uploads /tmp

2Fix

Create a directory owned by the PHP user and point upload_tmp_dir at it in php.ini. This directive cannot be set in .htaccess or .user.ini, so edit the main php.ini (or the FPM pool file) and reload PHP.

sudo mkdir -p /var/tmp/php-uploads
sudo chown www-data:www-data /var/tmp/php-uploads
sudo chmod 700 /var/tmp/php-uploads
# php.ini
# upload_tmp_dir = "/var/tmp/php-uploads"
sudo systemctl reload php8.3-fpm

3Verify

Reload the debug page: upload_tmp_dir shows the new path, and a small test upload succeeds.

php -i | grep -i upload_tmp_dir

Confirmed by php.net

Did this fix it?

Cause 2 of 4

The whole request is bigger than post_max_size

1Check

When the POST body exceeds post_max_size, PHP discards it and leaves $_POST and $_FILES empty. The default is 8M. Compare the request size with the limit.

<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST' && empty($_POST) && empty($_FILES)) {
    echo 'Body size: ', $_SERVER['CONTENT_LENGTH'] ?? 0, ' limit: ', ini_get('post_max_size');
}

2Fix

Raise post_max_size above upload_max_filesize, and keep memory_limit above post_max_size.

; php.ini
upload_max_filesize = 64M
post_max_size = 72M
memory_limit = 128M

3Verify

Upload a file just under the new limit and check that $_FILES is filled.

php -i | grep -E 'post_max_size|upload_max_filesize|memory_limit'

Confirmed by php.net

Did this fix it?

Cause 3 of 4

One file is bigger than upload_max_filesize

1Check

upload_max_filesize caps each single file and defaults to 2M. Read the error value and the size.

<?php
var_dump($_FILES['userfile']['error'] === UPLOAD_ERR_OK, ini_get('upload_max_filesize'));

2Fix

Raise upload_max_filesize, with post_max_size larger than it. If a MAX_FILE_SIZE hidden field is in the form, it can only lower the limit, never raise it past this setting.

; php.ini or the pool's php_admin_value
upload_max_filesize = 64M
post_max_size = 72M

3Verify

Restart PHP, repeat the upload and confirm the error value is UPLOAD_ERR_OK.

sudo systemctl reload php8.3-fpm

Confirmed by php.net

Did this fix it?

Cause 4 of 4

More files than max_file_uploads in one request

1Check

max_file_uploads (default 20) limits how many files one submission can carry. After the limit, $_FILES stops processing further files.

<?php
echo count($_FILES['pictures']['name']), ' of ', ini_get('max_file_uploads');

2Fix

Raise max_file_uploads, or send the files in batches from the browser.

; php.ini
max_file_uploads = 50

3Verify

Submit more than 20 files and count the entries again.

php -i | grep max_file_uploads

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • Set upload_tmp_dir to a directory that exists, is owned by the PHP user and has enough free space for the largest upload.
  • Keep post_max_size larger than upload_max_filesize, and the web server body limit larger than both.
  • Check the error value of every uploaded file before calling move_uploaded_file.

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

CodeIgniter 4 cannot write its cache files

CodeIgniter\Cache\Exceptions\CacheException: Cache unable to write to /var/www/app/writable/cache/

CodeIgniter 4's file cache needs a cache directory that the web server can really write to.

2 causes, each with a fix

Back end

CodeIgniter 3 loads the model but the property is undefined

The model name you are loading is the name of a resource that is already being used: user

CodeIgniter 3 expects a model file named like its class, with the first letter capitalised, for example User_model.php holding class User_model.

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.