laravel/framework · error · RuntimeException

To enable support for guessing extensions, please install th

Error message

To enable support for guessing extensions, please install the symfony/mime package.

What it means

Thrown by Filesystem::guessExtension() when Symfony\Component\Mime\MimeTypes is not loadable. guessExtension maps a file's MIME type back to one or more extensions using symfony/mime's reverse lookup table; without that package the mapping is unavailable and the method refuses to guess.

Source

Thrown at src/Illuminate/Filesystem/Filesystem.php:444

     * @return string
     */
    public function extension($path)
    {
        return pathinfo($path, PATHINFO_EXTENSION);
    }

    /**
     * Guess the file extension from the MIME type of a given file.
     *
     * @param  string  $path
     * @return string|null
     *
     * @throws \RuntimeException
     */
    public function guessExtension($path)
    {
        if (! class_exists(MimeTypes::class)) {
            throw new RuntimeException(
                'To enable support for guessing extensions, please install the symfony/mime package.'
            );
        }

        return (new MimeTypes)->getExtensions($this->mimeType($path))[0] ?? null;
    }

    /**
     * Get the file type of a given file.
     *
     * @param  string  $path
     * @return string|false
     */
    public function type($path)
    {
        return filetype($path);
    }

View on GitHub (pinned to bd6b5437e6)

Solutions

Install the package: `composer require symfony/mime`.
If you only need the MIME type (not the extension), use File::mimeType() which uses PHP's finfo and needs no extra package.
Fall back to File::extension($path) for a purely path-based extension.

Example fix

// before - throws without symfony/mime
$ext = File::guessExtension($path);

// after
// shell: composer require symfony/mime
// or alternative without the package:
$ext = File::extension($path);

Defensive patterns

Strategy: validation

Validate before calling

if (! class_exists(\Symfony\Component\Mime\MimeTypes::class)) {
    return File::extension($path); // fallback
}
return File::guessExtension($path);

Type guard

function mimeGuessingAvailable(): bool
{
    return class_exists(\Symfony\Component\Mime\MimeTypes::class);
}

Try / catch

try {
    return File::guessExtension($path);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'symfony/mime')) {
        return File::extension($path);
    }
    throw $e;
}

Prevention

Add symfony/mime to composer.json if you call guessExtension().
Fall back to File::extension() when the package is optional.
Document optional dependencies.

When it happens

Trigger: Calling File::guessExtension($path) where symfony/mime is not installed (it is optional for illuminate/filesystem).

Common situations: Slim install of illuminate/filesystem without symfony/mime; building a minimal SaaS that pulls only selected Illuminate packages; CI image that prunes dev/suggest dependencies.

Related errors

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/c26c28e09bcd88ea.json. Report an issue: GitHub.