laravel/framework · error · InvalidArgumentException

Scoped disk is missing "disk" configuration option.

Error message

Scoped disk is missing "disk" configuration option.

What it means

Thrown by FilesystemManager::createScopedDriver() when a disk configured with 'driver' => 'scoped' omits the 'disk' key. A scoped disk layers a path prefix onto an existing parent disk, so the parent disk name must be specified; without it there is nothing to scope.

Source

Thrown at src/Illuminate/Filesystem/FilesystemManager.php:301

                $config['credentials']['token'] = $config['token'];
            }
        }

        return Arr::except($config, ['token']);
    }

    /**
     * Create a scoped driver.
     *
     * @param  array  $config
     * @return \Illuminate\Contracts\Filesystem\Filesystem
     *
     * @throws \InvalidArgumentException
     */
    public function createScopedDriver(array $config)
    {
        if (empty($config['disk'])) {
            throw new InvalidArgumentException('Scoped disk is missing "disk" configuration option.');
        } elseif (empty($config['prefix'])) {
            throw new InvalidArgumentException('Scoped disk is missing "prefix" configuration option.');
        }

        return $this->build(tap(
            is_string($config['disk']) ? $this->getConfig($config['disk']) : $config['disk'],
            function (&$parent) use ($config) {
                if (empty($parent['prefix'])) {
                    $parent['prefix'] = $config['prefix'];
                } else {
                    $separator = $parent['directory_separator'] ?? DIRECTORY_SEPARATOR;

                    $parentPrefix = rtrim($parent['prefix'], $separator);
                    $scopedPrefix = ltrim($config['prefix'], $separator);

                    $parent['prefix'] = "{$parentPrefix}{$separator}{$scopedPrefix}";
                }

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Add 'disk' => 's3' (or whichever parent) to the scoped disk config.
2. Ensure the referenced parent disk is itself defined under filesystems.disks.
3. Use the correct keys: scoped disks need both 'disk' and 'prefix'.

Example fix

// before
// 'disks' => ['tenants' => ['driver' => 'scoped', 'prefix' => 'tenant-a']]

// after
// 'disks' => [
//     'tenants' => ['driver' => 'scoped', 'disk' => 's3', 'prefix' => 'tenant-a'],
// ]

$cfg = config("filesystems.disks.{$name}");
if (($cfg['driver'] ?? null) === 'scoped' && empty($cfg['disk'])) {
    throw new RuntimeException('Scoped disk requires a "disk" option');
}

function scopedDiskHasParent(array $config): bool
{
    return ($config['driver'] ?? '') === 'scoped' && !empty($config['disk']);
}

try {
    return Storage::disk($name);
} catch (\InvalidArgumentException $e) {
    if (str_contains($e->getMessage(), 'missing "disk"')) {
        abort(500, 'Scoped disk misconfigured: missing parent disk');
    }
    throw $e;
}

When it happens

Trigger: Defining a scoped disk in config/filesystems.php with 'driver' => 'scoped' but no 'disk' key, then calling Storage::disk() on it.

Common situations: Setting up multi-tenant path prefixes; copying a scoped disk example but forgetting the parent disk reference; typoing 'disk' as 'parent' or 'base'.

Related errors

• Scoped disk is missing "prefix" configuration option.
• Database file at path [{$path}] does not exist. Ensure this
• Database connection [{$name}] not configured.
• This driver does not support retrieving URLs.
• Unknown visibility: {$visibility}.

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