$request->file() is null although a file was selected
$request->file('photo') returns nullShort answer
If $request->file('photo') is null, the file never reached PHP as an upload. Check three things in order: the form has enctype="multipart/form-data", the input name matches the key you read, and the file is smaller than post_max_size and upload_max_filesize, because PHP then empties $_FILES.
Fix it fast
1Find out which cause you have
List everything the request actually carries. If the key you expect is not in files, the problem is before your controller.
// temporary line at the top of the controller method dd($request->allFiles(), $request->all());2Match what you see, then jump to its fix
- 1
allFiles() is empty, and the form posts the file name as plain text in all()The form lacks enctype="multipart/form-data"Fix - 2
allFiles() lists a key, but not the one passed to file()The name you read differs from the input's name attributeFix - 3
Small files work, large ones give an empty $_FILES and empty form fieldsThe upload is larger than PHP allows, so PHP drops the whole request bodyFix
- 1
What does the error look like?
$request->file('photo') returns null$request->hasFile('photo') returns false$_FILES is empty on a request with a large file
Cause 1 of 3
The form lacks enctype="multipart/form-data"
1Check
The PHP manual says the upload form must have the multipart/form-data enctype, otherwise the upload will not work.
grep -n "<form" resources/views/profile/edit.blade.php2Fix
Add the attribute to the form tag. For an AJAX call, send a FormData object and do not set Content-Type by hand.
<form action="/profile" method="POST" enctype="multipart/form-data">
@csrf
<input type="file" name="photo">
</form>3Verify
Submit again: dd($request->allFiles()) now lists photo.
php artisan route:list --path=profileConfirmed by php.net
Cause 2 of 3
The name you read differs from the input's name attribute
1Check
file('photo') reads the input whose name attribute is photo. Names with brackets, such as photos[], come back as an array.
grep -n "type=\"file\"" resources/views -r2Fix
Use the exact key shown by allFiles(), and loop when the input is multiple.
$file = $request->file('photo');
if ($request->hasFile('photo') && $request->file('photo')->isValid()) {
$path = $request->file('photo')->store('photos');
}3Verify
The store() call returns a path and the file exists on the disk.
ls storage/app/private/photosConfirmed by laravel.com
Cause 3 of 3
The upload is larger than PHP allows, so PHP drops the whole request body
1Check
The PHP manual says that when post data is larger than post_max_size, $_POST and $_FILES are empty. post_max_size must also be larger than upload_max_filesize.
php -i | grep -E "^(post_max_size|upload_max_filesize)"2Fix
Raise both limits in the php.ini used by PHP-FPM, keeping post_max_size above upload_max_filesize, then restart PHP-FPM.
; php.ini (FPM)
upload_max_filesize = 20M
post_max_size = 25M3Verify
Upload a file near the new limit and check that allFiles() lists it.
sudo systemctl restart php8.3-fpmConfirmed by php.net
How do I stop it coming back?
- Keep the PHP limits and the web server limit in one documented place.
- Check isValid() before storing: Laravel documents it for catching problems during the upload.
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
Composer says the gd extension is missing on a Laravel project
composer install or composer update stops on a package that requires ext-gd
Composer refuses to install a package that requires ext-gd when the PHP binary running Composer has no GD extension.
4 causes, each with a fixBack end
composer require maatwebsite/excel fails to install
Composer says the package needs an older PHP than the one installed
Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.
3 causes, each with a fixBack end
composer install says the lock file is not compatible and asks for update
Your lock file does not contain a compatible set of packages. Please run composer update.
composer install checked the locked packages against this machine's PHP and extensions and found a conflict.
3 causes, each with a fixBack end
composer require laravel/horizon fails: ext-pcntl is missing
laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system
Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.
3 causes, each with a fixBack end
composer require laravel/passport stops with 'requirements could not be resolved'
... but these were not loaded, likely because it conflicts with another require.
Composer found no Passport release that fits your project at once.
4 causes, each with a fixBack end
Composer says the root composer.json requires a PHP version your PHP does not satisfy
Your requirements could not be resolved to an installable set of packages.
Composer compares the php constraint in your composer.json, or in a package, with the PHP that runs Composer.
3 causes, each with a fix