{"record":{"id":"66f8c744decae377","repo":"mongodb/laravel-mongodb","slug":"unexpected-value-for-gridfs-bucket-configuration-expecting-s","errorCode":null,"errorMessage":"Unexpected value for GridFS \"bucket\" configuration. Expecting \"%s\". Got \"%s\"","messagePattern":"Unexpected value for GridFS \"bucket\" configuration\\. Expecting \"(.+?)\"\\. Got \"(.+?)\"","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/MongoDBServiceProvider.php","lineNumber":145,"sourceCode":"                    // Get the bucket from a factory function\n                    $bucket = $bucket($app, $config);\n                } elseif (is_string($bucket) && $app->has($bucket)) {\n                    // Get the bucket from a service\n                    $bucket = $app->get($bucket);\n                } elseif (is_string($bucket) || $bucket === null) {\n                    // Get the bucket from the database connection\n                    $connection = $app['db']->connection($config['connection']);\n                    if (! $connection instanceof Connection) {\n                        throw new InvalidArgumentException(sprintf('The database connection \"%s\" does not use the \"mongodb\" driver.', $config['connection'] ?? $app['config']['database.default']));\n                    }\n\n                    $bucket = $connection->getClient()\n                        ->getDatabase($config['database'] ?? $connection->getDatabaseName())\n                        ->selectGridFSBucket(['bucketName' => $config['bucket'] ?? 'fs', 'disableMD5' => true]);\n                }\n\n                if (! $bucket instanceof Bucket) {\n                    throw new InvalidArgumentException(sprintf('Unexpected value for GridFS \"bucket\" configuration. Expecting \"%s\". Got \"%s\"', Bucket::class, get_debug_type($bucket)));\n                }\n\n                $adapter = new GridFSAdapter($bucket, $config['prefix'] ?? '');\n\n                /** @see FilesystemManager::createFlysystem() */\n                if ($config['read-only'] ?? false) {\n                    if (! class_exists(ReadOnlyFilesystemAdapter::class)) {\n                        throw new RuntimeException('Read-only Adapter for Flysystem is missing. Try running \"composer require league/flysystem-read-only\"');\n                    }\n\n                    $adapter = new ReadOnlyFilesystemAdapter($adapter);\n                }\n\n                /** Prevent using backslash on Windows in {@see FilesystemAdapter::__construct()} */\n                $config['directory_separator'] = '/';\n\n                return new FilesystemAdapter(new Filesystem($adapter, $config), $adapter, $config);\n            });","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/mongodb/laravel-mongodb/blob/0634653039468ceb0268a69192bdac64469ed043/src/MongoDBServiceProvider.php#L127-L163","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Ensure the 'bucket' config value is either a string bucket name (handled via selectGridFSBucket) or a MongoDB\\GridFS\\Bucket instance.","If passing an object, construct it with (new Client())->getDatabase($db)->selectGridFSBucket(['bucketName' => 'fs']).","Dump get_debug_type($config['bucket']) to see what type is actually being supplied.","Update config/database.php so the gridfs disk only sets 'bucket' => 'fs' (or omits it) plus database/prefix keys."],"exampleFix":"// before\n'bucket' => ['name' => 'fs'],\n// after\n'bucket' => 'fs',","handlingStrategy":"validation","validationCode":"$disk = config('database.filesystems.disks.gridfs');\n$bucket = $disk['bucket'] ?? 'fs';\nif (! is_string($bucket) && ! $bucket instanceof MongoDB\\GridFS\\Bucket) {\n    throw new InvalidArgumentException('bucket must be a string or GridFS Bucket, got ' . get_debug_type($bucket));\n}","typeGuard":"function isValidGridFSBucket(mixed $v): bool { return is_string($v) || $v instanceof MongoDB\\GridFS\\Bucket; }","tryCatchPattern":"try {\n    Storage::disk('gridfs')->put($path, $contents);\n} catch (InvalidArgumentException $e) {\n    if (str_contains($e->getMessage(), 'GridFS \"bucket\" configuration')) {\n        Log::error('Invalid GridFS bucket config', ['config' => config('filesystems.disks.gridfs')]);\n    }\n    throw $e;\n}","preventionTips":["Keep 'bucket' as a plain string like 'fs' in config/database.php","Never store arrays/objects in the 'bucket' config key unless they are MongoDB\\GridFS\\Bucket instances","Validate disk config in a config sanity test","Dump get_debug_type() when debugging config values"],"tags":["gridfs","flysystem","config","type-mismatch"],"backgroundTag":"invalid-config-value","analyzedSha":"0634653039468ceb0268a69192bdac64469ed043","analyzedAt":"2026-09-15T02:56:37.067Z","contentChangedAt":"2026-09-15T02:56:37.067Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}