laravel/framework · error · RuntimeException

To enable support for relative links, please install the…

Error message

To enable support for relative links, please install the symfony/filesystem package.

What it means

Thrown by Filesystem::relativeLink() when the Symfony\Component\Filesystem\Filesystem class is not autoloadable. Laravel computes relative symlinks by delegating path arithmetic to symfony/filesystem's makePathRelative(); without that package the operation cannot be performed safely, so it errors rather than silently producing a broken link.

Solutions

Run composer require symfony/filesystem.
If you do not need a relative link, use File::link($target, $link) for an absolute symlink instead.
Verify the package is present in composer.lock after deploy: composer show symfony/filesystem.
Pin the package in composer.json so it is not stripped by dependency resolution.

Example fix

// before
File::relativeLink($target, $link); // throws if symfony/filesystem absent

// after (terminal)
// composer require symfony/filesystem
File::relativeLink($target, $link);

Defensive patterns

Strategy: validation

Validate before calling

if (! class_exists(\Symfony\Component\Filesystem\Filesystem::class)) {
    throw new RuntimeException('Run: composer require symfony/filesystem');
}
File::relativeLink($target, $link);

Type guard

function supportsRelativeLink(): bool {
    return class_exists(\Symfony\Component\Filesystem\Filesystem::class);
}

Try / catch

try {
    File::relativeLink($target, $link);
} catch (\RuntimeException $e) {
    File::link($target, $link); // absolute fallback
}

Prevention

Require symfony/filesystem if you use relativeLink().
Use absolute File::link() when the relative form is not needed.
Verify composer.lock after dependency changes.
Document optional dependencies in your README.

When it happens

Trigger: Calling File::relativeLink($target, $link) (often via storage:link with relative paths, or during package asset publishing) in a project where composer has not installed symfony/filesystem.

Common situations: Slimmed dependency tree where symfony/filesystem was removed; using a standalone subset of Illuminate\Filesystem outside a full Laravel app; composer install --no-dev against a constraint that dropped the package.

Related errors

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

Appendix: source

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

        $mode = $this->isDirectory($target) ? 'J' : 'H';

        exec("mklink /{$mode} ".escapeshellarg($link).' '.escapeshellarg($target));
    }

    /**
     * Create a relative symlink to the target file or directory.
     *
     * @param  string  $target
     * @param  string  $link
     * @return void
     *
     * @throws \RuntimeException
     */
    public function relativeLink($target, $link)
    {
        if (! class_exists(SymfonyFilesystem::class)) {
            throw new RuntimeException(
                'To enable support for relative links, please install the symfony/filesystem package.'
            );
        }

        $relativeTarget = (new SymfonyFilesystem)->makePathRelative($target, dirname($link));

        $this->link($this->isFile($target) ? rtrim($relativeTarget, '/') : $relativeTarget, $link);
    }

    /**
     * Extract the file name from a file path.
     *
     * @param  string  $path
     * @return string
     */
    public function name($path)
    {
        return pathinfo($path, PATHINFO_FILENAME);

View on GitHub (pinned to e0f6eb3518)