mongodb/laravel-mongodb · error · InvalidArgumentException

Unexpected value for GridFS "bucket" configuration…

Error message

Unexpected value for GridFS "bucket" configuration. Expecting "%s". Got "%s"

What it means

This error is thrown by the GridFS flysystem adapter registration when the resolved 'bucket' value is not an instance of MongoDB\GridFS\Bucket. The config key 'bucket' normally holds a string bucket name, but this branch runs when a pre-constructed Bucket object (or other value) was supplied and it failed the instanceof check.

Solutions

  1. Ensure the 'bucket' config value is either a string bucket name (handled via selectGridFSBucket) or a MongoDB\GridFS\Bucket instance.
  2. If passing an object, construct it with (new Client())->getDatabase($db)->selectGridFSBucket(['bucketName' => 'fs']).
  3. Dump get_debug_type($config['bucket']) to see what type is actually being supplied.
  4. Update config/database.php so the gridfs disk only sets 'bucket' => 'fs' (or omits it) plus database/prefix keys.

Example fix

// before
'bucket' => ['name' => 'fs'],
// after
'bucket' => 'fs',
Defensive patterns

Strategy: validation

Validate before calling

$disk = config('database.filesystems.disks.gridfs');
$bucket = $disk['bucket'] ?? 'fs';
if (! is_string($bucket) && ! $bucket instanceof MongoDB\GridFS\Bucket) {
    throw new InvalidArgumentException('bucket must be a string or GridFS Bucket, got ' . get_debug_type($bucket));
}

Type guard

function isValidGridFSBucket(mixed $v): bool { return is_string($v) || $v instanceof MongoDB\GridFS\Bucket; }

Try / catch

try {
    Storage::disk('gridfs')->put($path, $contents);
} catch (InvalidArgumentException $e) {
    if (str_contains($e->getMessage(), 'GridFS "bucket" configuration')) {
        Log::error('Invalid GridFS bucket config', ['config' => config('filesystems.disks.gridfs')]);
    }
    throw $e;
}

Prevention

When it happens

Trigger: Registering a 'gridfs' flysystem disk where the 'bucket' config entry resolves to something that is neither a valid bucket name nor a MongoDB\GridFS\Bucket instance — e.g. passing an array, a closure, or a wrong object type as 'bucket'.

Common situations: Developers copy a bucket object from another connection library, typo the config key so an unrelated value lands in $bucket, or upgrade the package and pass a legacy bucket wrapper class instead of MongoDB\GridFS\Bucket.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of mongodb/laravel-mongodb@0634653039 (2026-09-15). Data as JSON: /api/errors/66f8c744decae377. Report an issue: GitHub.

Appendix: source

Thrown at src/MongoDBServiceProvider.php:145

                    // Get the bucket from a factory function
                    $bucket = $bucket($app, $config);
                } elseif (is_string($bucket) && $app->has($bucket)) {
                    // Get the bucket from a service
                    $bucket = $app->get($bucket);
                } elseif (is_string($bucket) || $bucket === null) {
                    // Get the bucket from the database connection
                    $connection = $app['db']->connection($config['connection']);
                    if (! $connection instanceof Connection) {
                        throw new InvalidArgumentException(sprintf('The database connection "%s" does not use the "mongodb" driver.', $config['connection'] ?? $app['config']['database.default']));
                    }

                    $bucket = $connection->getClient()
                        ->getDatabase($config['database'] ?? $connection->getDatabaseName())
                        ->selectGridFSBucket(['bucketName' => $config['bucket'] ?? 'fs', 'disableMD5' => true]);
                }

                if (! $bucket instanceof Bucket) {
                    throw new InvalidArgumentException(sprintf('Unexpected value for GridFS "bucket" configuration. Expecting "%s". Got "%s"', Bucket::class, get_debug_type($bucket)));
                }

                $adapter = new GridFSAdapter($bucket, $config['prefix'] ?? '');

                /** @see FilesystemManager::createFlysystem() */
                if ($config['read-only'] ?? false) {
                    if (! class_exists(ReadOnlyFilesystemAdapter::class)) {
                        throw new RuntimeException('Read-only Adapter for Flysystem is missing. Try running "composer require league/flysystem-read-only"');
                    }

                    $adapter = new ReadOnlyFilesystemAdapter($adapter);
                }

                /** Prevent using backslash on Windows in {@see FilesystemAdapter::__construct()} */
                $config['directory_separator'] = '/';

                return new FilesystemAdapter(new Filesystem($adapter, $config), $adapter, $config);
            });

View on GitHub (pinned to 0634653039)