laravel/framework · error · RuntimeException

To enable support for guessing extensions, please install…

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 autoloadable. guessExtension() infers a file extension from MIME type by delegating to symfony/mime; without the package the lookup cannot run. Laravel refuses to fall back to a naive guess because that would produce misleading extensions.

Solutions

Run composer require symfony/mime.
If extension guessing is optional, fall back to pathinfo($path, PATHINFO_EXTENSION) when the package is absent.
Verify presence in CI: composer show symfony/mime.
Pin the version compatible with your laravel/framework constraint.

Example fix

// before
$ext = File::guessExtension($path);

// after (terminal)
// composer require symfony/mime
$ext = File::guessExtension($path);

Defensive patterns

Strategy: validation

Validate before calling

if (! class_exists(\Symfony\Component\Mime\MimeTypes::class)) {
    throw new RuntimeException('Run: composer require symfony/mime');
}
return File::guessExtension($path);

Type guard

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

Try / catch

try {
    $ext = File::guessExtension($path);
} catch (\RuntimeException $e) {
    $ext = pathinfo($path, PATHINFO_EXTENSION) ?: null;
}

Prevention

Require symfony/mime for upload validation.
Fall back to pathinfo() when guessing is unavailable.
Verify presence of symfony/mime in CI.
Pin compatible versions in composer.json.

When it happens

Trigger: Calling File::guessExtension($path) (often indirectly via upload validation or UploadedFile handling) when symfony/mime is not installed.

Common situations: Custom minimal Laravel install that excluded symfony/mime; production build step that stripped suggested packages; framework upgrade where symfony/mime moved from required to suggested.

Related errors

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/c26c28e09bcd88ea. Report an issue: GitHub.

Appendix: 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 e0f6eb3518)