mongodb/laravel-mongodb · error · RuntimeException

GridFS adapter for Flysystem is missing. Try running…

Error message

GridFS adapter for Flysystem is missing. Try running "composer require league/flysystem-gridfs"

What it means

Thrown in the 'gridfs' filesystem extension registration when class_exists(GridFSAdapter::class) fails, meaning the league/flysystem-gridfs package is not installed. The adapter class is only autoloaded if the Composer package is present, so any attempt to configure a gridfs disk before installing it fails at resolution time with a RuntimeException pointing at the missing Composer requirement.

Solutions

1. Run composer require league/flysystem-gridfs to install the missing adapter.
2. Verify the package is in the composer.json of the deployed environment (it may be absent in production).
3. Use a non-GridFS filesystem disk until the adapter dependency is installed.

When it happens

Trigger: Thrown at src/MongoDBServiceProvider.php:121 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at src/MongoDBServiceProvider.php:121

        // Add connector for queue support.
        $this->app->resolving('queue', function ($queue) {
            $queue->addConnector('mongodb', function () {
                return new MongoConnector($this->app['db']);
            });
        });

        $this->registerFlysystemAdapter();
        $this->registerScoutEngine();
        $this->registerBoostTools();
    }

    private function registerFlysystemAdapter(): void
    {
        // GridFS adapter for filesystem
        $this->app->resolving('filesystem', static function (FilesystemManager $filesystemManager) {
            $filesystemManager->extend('gridfs', function (Application $app, array $config) {
                if (! class_exists(GridFSAdapter::class)) {
                    throw new RuntimeException('GridFS adapter for Flysystem is missing. Try running "composer require league/flysystem-gridfs"');
                }

                $bucket = $config['bucket'] ?? null;

                if ($bucket instanceof Closure) {
                    // 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()

View on GitHub (pinned to 0634653039)