Maaz Zindani

Loading the index…

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

$request->file() is null although a file was selected

Error$request->file('photo') returns null

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

  • Applies to Laravel 12, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1allFiles() is empty, and the form posts the file name as plain text in all()The form lacks enctype="multipart/form-data"Fix
    2. 2allFiles() lists a key, but not the one passed to file()The name you read differs from the input's name attributeFix
    3. 3Small 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

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

2Fix

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=profile

Confirmed by php.net

Did this fix it?

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 -r

2Fix

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/photos

Confirmed by laravel.com

Did this fix it?

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

3Verify

Upload a file near the new limit and check that allFiles() lists it.

sudo systemctl restart php8.3-fpm

Confirmed by php.net

Did this fix it?

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 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 fix

Back 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.