A PHP upload fails or $_FILES comes back empty
$_FILES is an empty array after a POST with a fileShort 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.
Fix it fast
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);2Match what you see, then jump to its fix
- 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
Both $_POST and $_FILES are empty, with no error code to readThe whole request is bigger than post_max_sizeFix - 3
The file entry exists in $_FILES but its error value is not UPLOAD_ERR_OKOne file is bigger than upload_max_filesizeFix - 4
A multi-file form returns only the first 20 filesMore files than max_file_uploads in one requestFix
- 1
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 uploadmove_uploaded_file() returns falseSetting 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 /tmp2Fix
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-fpm3Verify
Reload the debug page: upload_tmp_dir shows the new path, and a small test upload succeeds.
php -i | grep -i upload_tmp_dirConfirmed by php.net
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 = 128M3Verify
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
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 = 72M3Verify
Restart PHP, repeat the upload and confirm the error value is UPLOAD_ERR_OK.
sudo systemctl reload php8.3-fpmConfirmed by php.net
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 = 503Verify
Submit more than 20 files and count the entries again.
php -i | grep max_file_uploadsConfirmed by php.net
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
PHP $_POST is empty even though the form or client sent data
var_dump($_POST) prints array(0) {}
PHP fills $_POST only for application/x-www-form-urlencoded and multipart/form-data.
4 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 fixBack end
AWS SDK for PHP rejects requests: the signature is from the future
Signature not yet current: {date} is still later than {date}
AWS compares the timestamp in your signed request with its own clock.
2 causes, each with a fixBack 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 fixBack 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