Maaz Zindani

Loading the index…

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

A CSV or Excel upload fails Laravel's mimes validation although the extension is right

ErrorValidation fails on a .csv or .xlsx upload that opens fine in Excel

Short answer

Laravel's mimes rule and File::types() do not trust the file name. They read the file's contents, guess a MIME type, and compare it to the extensions you listed. A CSV saved by Excel, or a spreadsheet renamed to .csv, can be guessed as something else and fail. Print the guess, then validate with the extension rule plus a content rule.

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

Fix it fast

  1. 1Find out which cause you have

    Print what Laravel actually sees for the rejected file: the extension it guessed from the contents and the extension the user gave it. They usually differ.

    $file = $request->file('upload');
    logger()->info('upload check', [
        'guessed_extension' => $file->extension(),
        'client_name' => $file->getClientOriginalName(),
    ]);
  2. 2Match what you see, then jump to its fix

    1. 1The file opens fine in Excel, the name ends in .csv or .xlsx, yet validation says it is not that typeThe content guess does not match the extensions in the ruleFix
    2. 2A .xls or .ods file saved with a .csv or .xlsx name is rejected, or a file named .txt with valid content is acceptedThe file was renamed, so name and content disagreeFix

What does the error look like?

  • Validation fails on a .csv or .xlsx upload that opens fine in Excel
  • mimes:csv or File::types(['csv']) rejects the file

Cause 1 of 2

The content guess does not match the extensions in the rule

1Check

mimes and File::types() read the file's contents and guess a MIME type, which can differ from what the browser sent. Compare the guessed extension from the first step with your list.

// in tinker or a test, for the failing file
$file->extension();

2Fix

Look up the type that matches your real files in the Apache mime.types list the Laravel docs point to, then validate the content with mimetypes and the user-given name with extensions, as the docs recommend using them together.

$request->validate([
    'upload' => [
        'required',
        'file',
        'extensions:csv,xlsx',
        'mimetypes:text/plain,text/csv', // add the types your real files report
    ],
]);

3Verify

Upload one real .csv and one real .xlsx and confirm both pass.

php artisan test --filter=ImportUploadTest

Confirmed by laravel.com

Did this fix it?

Cause 2 of 2

The file was renamed, so name and content disagree

1Check

The mimes rule does not check that the extension and the content agree. A file whose content is a different format fails a mimes list; a file with right content but another name can still pass it.

$file->extension();               // guessed from the contents
$file->getClientOriginalExtension(); // what the user typed

2Fix

Tell the user to export again in the requested format. In the rule, keep the extensions rule next to the content rule so both the name and the contents have to match.

'upload' => ['required', 'extensions:csv', 'mimetypes:text/plain,text/csv'],

3Verify

Rename a PDF to .csv and confirm it is now rejected.

php artisan test --filter=ImportUploadTest

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • Keep one test per accepted format that uploads a real sample file, so a framework or PHP upgrade that changes the content guess is caught.
  • Use extensions together with mimes or mimetypes, never the extension alone.
  • Show the user the accepted formats next to the upload field so they export correctly the first time.

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.