symfony/http-foundation · error · InvalidArgumentException

You must provide the "database" and "collection" option for…

Error message

You must provide the "database" and "collection" option for MongoDBSessionHandler.

What it means

MongoDbSessionHandler requires an explicit MongoDB database and collection name to know where sessions are stored. The constructor throws an InvalidArgumentException if either the 'database' or 'collection' key is missing from the $options array.

Solutions

Add both 'database' and 'collection' keys to the $options array passed to the constructor.
Verify the service/config definition that builds MongoDbSessionHandler passes the full options map (e.g. ['database' => 'app', 'collection' => 'sessions']).
Check that env-driven config variables for database/collection are actually set in the current environment.

Example fix

// before
$handler = new MongoDbSessionHandler($client, ['database' => 'app']);

// after
$handler = new MongoDbSessionHandler($client, ['database' => 'app', 'collection' => 'sessions']);

Defensive patterns

Strategy: validation

Validate before calling

if (empty($options['database']) || empty($options['collection'])) {
    throw new \InvalidArgumentException('database and collection are required for MongoDbSessionHandler');
}
$handler = new MongoDbSessionHandler($client, $options);

Try / catch

try {
    $handler = new MongoDbSessionHandler($client, $options);
} catch (\InvalidArgumentException $e) {
    // fix config and retry / fail fast with a clear config error
}

Prevention

Centralize session handler options in one validated config object.
Assert presence of 'database' and 'collection' in config loading tests.
Keep env vars for db/collection documented and checked at boot.

When it happens

Trigger: Instantiating MongoDbSessionHandler with an options array that omits 'database' or 'collection', e.g. new MongoDbSessionHandler($client, []) or passing only connection settings.

Common situations: Framework config (e.g. Symfony session handler services) missing the mongo db/collection keys; copying a DSN-only setup without handler options; renaming config keys during a refactor.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

AI-assisted analysis of symfony/http-foundation@5aea19cd67 (2026-09-13). Data as JSON: /api/errors/5e63453391fda864. Report an issue: GitHub.

Appendix: source

Thrown at Session/Storage/Handler/MongoDbSessionHandler.php:70

     * A TTL collections can be used on MongoDB 2.2+ to cleanup expired sessions
     * automatically. Such an index can for example look like this:
     *
     *     db.<session-collection>.createIndex(
     *         { "<expiry-field>": 1 },
     *         { "expireAfterSeconds": 0 }
     *     )
     *
     * More details on: https://docs.mongodb.org/manual/tutorial/expire-data/
     *
     * If you use such an index, you can drop `gc_probability` to 0 since
     * no garbage-collection is required.
     *
     * @throws \InvalidArgumentException When "database" or "collection" not provided
     */
    public function __construct(Client|Manager $mongo, array $options)
    {
        if (!isset($options['database']) || !isset($options['collection'])) {
            throw new \InvalidArgumentException('You must provide the "database" and "collection" option for MongoDBSessionHandler.');
        }

        if ($mongo instanceof Client) {
            $mongo = $mongo->getManager();
        }

        $this->manager = $mongo;
        $this->namespace = $options['database'].'.'.$options['collection'];

        $this->options = array_merge([
            'id_field' => '_id',
            'data_field' => 'data',
            'time_field' => 'time',
            'expiry_field' => 'expires_at',
        ], $options);
        $this->ttl = $this->options['ttl'] ?? null;
    }

View on GitHub (pinned to 5aea19cd67)