laravel/framework · error · RuntimeException

To enable support for relative links, please install the sym

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 loadable. Laravel delegates computing a portable relative path between target and link to symfony/filesystem's makePathRelative(); without that package the operation cannot be performed safely across platforms, so it errors rather than producing a wrong absolute link.

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 bd6b5437e6)

Solutions

Install the package: `composer require symfony/filesystem`.
If you cannot add it, use File::link() (absolute symlink) instead.
Pin a compatible version aligned with your Symfony components to avoid conflicts.

Example fix

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

// after - install it, or fall back to an absolute link
// shell: composer require symfony/filesystem
// or code:
File::link($target, $link);

Defensive patterns

Strategy: validation

Validate before calling

if (! class_exists(\Symfony\Component\Filesystem\Filesystem::class)) {
    // use absolute link instead
    File::link($target, $link);
} else {
    File::relativeLink($target, $link);
}

Type guard

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

Try / catch

try {
    File::relativeLink($target, $link);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'symfony/filesystem')) {
        File::link($target, $link);
    } else {
        throw $e;
    }
}

Prevention

Add symfony/filesystem to composer.json if you call relativeLink().
Check class_exists before calling in optional-dependency code.
Document optional deps in your package README.

When it happens

Trigger: Calling File::relativeLink($target, $link) in a project where composer did not install symfony/filesystem (it is a suggested, not required, dependency of illuminate/filesystem in slim installs).

Common situations: Using illuminate/filesystem outside a full Laravel app (e.g. a standalone script or micro-framework) that didn't require symfony/filesystem; aggressive dependency pruning; custom composer.json that excludes the package.

Related errors

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