Maaz Zindani

Loading the index…

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

A Laravel test using Storage::fake fails with 'Unable to retrieve the file_size'

ErrorUnable to retrieve the file_size for file

Short answer

Flysystem throws UnableToRetrieveMetadata when you ask for the size of a file that is not on that disk. In a test it means the file is not where you look: you faked or read a different disk, you used a different path than the upload got, or the write failed. Assert the file exists first and read the path the code returned.

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

Fix it fast

  1. 1Find out which cause you have

    Before asking for the size, ask the fake disk what it holds. Dump the file list of the disk you expect the upload to be on.

    Storage::disk('photos')->assertExists('photo1.jpg');
    dump(Storage::disk('photos')->allFiles());
  2. 2Match what you see, then jump to its fix

    1. 1dump(Storage::disk('photos')->allFiles()) is empty although the request returned 200The code under test writes to a different disk than the one you fakedFix
    2. 2allFiles() shows a file with a long hashed name, and you asked for the original nameThe test asks for a path that is not the stored pathFix
    3. 3assertExists fails and no exception was thrown while storingThe write failed silentlyFix
    4. 4Error comes from League\Flysystem, with a path, from code that does not use Laravel's StorageYou call fileSize on a path that never existed (plain Flysystem)Fix

What does the error look like?

  • Unable to retrieve the file_size for file
  • League\Flysystem\UnableToRetrieveMetadata
  • The same code works in the browser but fails in the test

Cause 1 of 4

The code under test writes to a different disk than the one you faked

1Check

Storage::fake('photos') replaces only the disk called photos. Calls without disk() go to the default disk, and store() or storeAs() use the default disk unless you give another name.

grep -rn "Storage::fake\|->store(\|storeAs(\|Storage::disk" app tests
grep -n "'default'" config/filesystems.php

2Fix

Fake the disk the application really uses, with the same name, in the test.

Storage::fake('public');   // the disk the controller writes to
// ...
Storage::disk('public')->assertExists($path);

3Verify

allFiles() on that disk now lists the upload and size() works.

php artisan test --filter=UploadTest

Confirmed by laravel.com

Did this fix it?

Cause 2 of 4

The test asks for a path that is not the stored path

1Check

store() and putFile() choose a unique file name for you and return the path. A test that guesses the name such as photo1.jpg looks at a file that does not exist. All paths are relative to the disk's root.

dump(Storage::disk('public')->allFiles());

2Fix

Use the path the code returned or saved in the database, or choose the name yourself with storeAs().

$path = $response->json('path');
Storage::disk('public')->assertExists($path);
$size = Storage::disk('public')->size($path);

3Verify

size() returns the number of bytes and the test passes.

php artisan test --filter=UploadTest

Confirmed by laravel.com

Did this fix it?

Cause 3 of 4

The write failed silently

1Check

When put() or another write cannot write the file, it returns false instead of throwing, unless the disk has the throw option. A later size() call is then the first thing that fails.

grep -n "'throw'" config/filesystems.php

2Fix

Turn on throw for the disk so the real write error (UnableToWriteFile) is raised at the write, and fix that one.

// config/filesystems.php
'public' => [
    'driver' => 'local',
    // ...
    'throw' => true,
],

3Verify

The test now fails at the write with a specific message, or passes.

php artisan test --filter=UploadTest

Confirmed by laravel.com

Did this fix it?

Cause 4 of 4

You call fileSize on a path that never existed (plain Flysystem)

1Check

Flysystem documents fileSize(), mimeType() and lastModified() as throwing UnableToRetrieveMetadata, and fileExists() as the check to run first.

grep -rn "fileSize(" app

2Fix

Check fileExists() before fileSize(), and catch UnableToRetrieveMetadata where a missing file is expected.

if ($filesystem->fileExists($path)) {
    $size = $filesystem->fileSize($path);
}

3Verify

The code returns a size for existing files and skips missing ones.

php artisan test

Confirmed by flysystem.thephpleague.com

Did this fix it?

How do I stop it coming back?

  • Fake the same disk name the code uses, and assert existence before any size or content check.
  • Return the stored path from the endpoint so tests can use it.
  • Set throw to true on disks in the testing environment so failed writes are loud.

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.