mongodb/laravel-mongodb · error · InvalidArgumentException

MongoDB connection configuration requires "dsn" or "host"…

Error message

MongoDB connection configuration requires "dsn" or "host" key.

What it means

Connection::getDsn() builds the MongoDB DSN from config. It returns a DSN from the 'dsn' key if present, else builds one from 'host'. If neither key is provided (or the 'dsn' string is empty and 'host' is empty), it throws InvalidArgumentException.

Solutions

Add a 'dsn' key to the connection config, e.g. 'dsn' => env('MONGODB_URI', 'mongodb://localhost:27017')
Or add a 'host' key, e.g. 'host' => ['localhost:27017']
Check env() defaults so local envs without variables still produce a usable host/DSN
Fix typos so the config key is exactly 'dsn' or 'host'

Example fix

// before
'mongodb' => ['driver' => 'mongodb'],
// after
'mongodb' => ['driver' => 'mongodb', 'dsn' => env('MONGODB_URI', 'mongodb://localhost:27017'), 'database' => 'myapp'],

Defensive patterns

Strategy: validation

Validate before calling

$config = config('database.connections.mongodb');
if (empty($config['dsn']) && empty($config['host'])) {
    throw new RuntimeException('mongodb connection needs dsn or host');
}

Type guard

function hasDsnOrHost(array $config): bool {
    return !empty($config['dsn']) || !empty($config['host']);
}

Try / catch

try {
    $conn = DB::connection('mongodb');
} catch (InvalidArgumentException $e) {
    if (str_contains($e->getMessage(), 'requires "dsn" or "host"')) {
        Log::error('MongoDB connection config missing dsn/host');
        // fix config, e.g. set MONGODB_URI env var
    } else {
        throw $e;
    }
}

Prevention

Use env('MONGODB_URI', 'mongodb://localhost:27017') in the dsn key
Add a config validation step in CI that checks required connection keys
Copy the sample connection block from the library README verbatim and edit values only

When it happens

Trigger: Defining a mongodb connection in config/database.php with only 'driver' => 'mongodb' and no 'dsn' or 'host' key; providing an empty 'host' array/string with no 'dsn'.

Common situations: New connection entry created from a copy that stripped both keys; config driven by env vars where both MONGODB_HOST and MONGODB_DSN are unset; misnamed key like 'hostname' instead of 'host'.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at src/Connection.php:346

        $authDatabase = isset($config['options']) && ! empty($config['options']['database']) ? $config['options']['database'] : null;

        return 'mongodb://' . implode(',', $hosts) . ($authDatabase ? '/' . $authDatabase : '');
    }

    /**
     * Create a DSN string from a configuration.
     */
    protected function getDsn(array $config): string
    {
        if (! empty($config['dsn'])) {
            return $this->getDsnString($config);
        }

        if (! empty($config['host'])) {
            return $this->getHostDsn($config);
        }

        throw new InvalidArgumentException('MongoDB connection configuration requires "dsn" or "host" key.');
    }

    /** @inheritdoc */
    #[Override]
    public function getDriverName()
    {
        return 'mongodb';
    }

    /** @inheritdoc */
    public function getDriverTitle()
    {
        return 'MongoDB';
    }

    /** @inheritdoc */
    #[Override]
    protected function getDefaultPostProcessor()

View on GitHub (pinned to 0634653039)