laravel/framework · error · InvalidArgumentException

A driver must be specified.

Error message

A driver must be specified.

What it means

Thrown by ConnectionFactory::createConnector() when the config array has no 'driver' key. The factory dispatches to a concrete Connector (MySQL, Postgres, SQLite, SQL Server) based on the driver string; without it there is no way to choose one, so it fails immediately rather than guessing.

Solutions

1. Add 'driver' => env('DB_CONNECTION', 'mysql') to the offending connection in config/database.php.
2. Ensure DB_CONNECTION is set in .env (mysql, pgsql, sqlite, sqlsrv).
3. Verify the connection name passed to DB::connection() actually exists in config and has a driver.
4. Clear config cache after editing: php artisan config:clear.

Example fix

// before
'myconn' => ['host' => env('DB_HOST', '127.0.0.1')],

// after
'myconn' => [
    'driver' => env('DB_CONNECTION', 'mysql'),
    'host'   => env('DB_HOST', '127.0.0.1'),
],

if (! isset($config['driver'])) {
    throw new \InvalidArgumentException(
        "Connection config '{$name}' is missing the 'driver' key."
    );
}

function hasDriver(array $config): bool {
    return isset($config['driver']) && is_string($config['driver']) && $config['driver'] !== '';
}

When it happens

Trigger: Calling $factory->createConnector($config) (directly, or via DatabaseManager when a connection is first opened) where $config['driver'] is unset. Triggered the first time DB::connection($name) is resolved.

Common situations: .env with DB_CONNECTION empty; config/database.php connection entry missing the 'driver' line; a connection name referenced in code that maps to an incomplete config stub; typo in the env var name read by the driver key.

Related errors

• Unsupported driver [ ].
• Unsupported driver [ ].
• Auth driver [ ] for guard [ ] is not defined.
• Database connection [ ] not configured.
• Database file at path

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/815f57a2bb21c094. Report an issue: GitHub.

Appendix: source

Thrown at src/Illuminate/Database/Connectors/ConnectionFactory.php:273

     * @return \Closure
     */
    protected function createPdoResolverWithoutHosts(array $config)
    {
        return fn () => $this->createConnector($config)->connect($config);
    }

    /**
     * Create a connector instance based on the configuration.
     *
     * @param  array  $config
     * @return \Illuminate\Database\Connectors\ConnectorInterface
     *
     * @throws \InvalidArgumentException
     */
    public function createConnector(array $config)
    {
        if (! isset($config['driver'])) {
            throw new InvalidArgumentException('A driver must be specified.');
        }

        if ($this->container->bound($key = "db.connector.{$config['driver']}")) {
            return $this->container->make($key);
        }

        return match ($config['driver']) {
            'mysql' => new MySqlConnector,
            'mariadb' => new MariaDbConnector,
            'pgsql' => new PostgresConnector,
            'sqlite' => new SQLiteConnector,
            'sqlsrv' => new SqlServerConnector,
            default => throw new InvalidArgumentException("Unsupported driver [{$config['driver']}]."),
        };
    }

    /**
     * Create a new connection instance.

View on GitHub (pinned to e0f6eb3518)