laravel/framework · error · InvalidArgumentException

Database connection [{$name}] not configured.

Error message

Database connection [{$name}] not configured.

What it means

Thrown by DatabaseManager::configuration() when there is no config entry at database.connections.{name} (and no dynamic connection config registered for that name). It guards every connection resolution against an undefined name.

Source

Thrown at src/Illuminate/Database/DatabaseManager.php:226

        return $this->factory->make($config, $name);
    }

    /**
     * Get the configuration for a connection.
     *
     * @param  string  $name
     * @return array
     *
     * @throws \InvalidArgumentException
     */
    protected function configuration($name)
    {
        $connections = $this->app['config']['database.connections'];

        $config = $this->dynamicConnectionConfigurations[$name] ?? Arr::get($connections, $name);

        if (is_null($config)) {
            throw new InvalidArgumentException("Database connection [{$name}] not configured.");
        }

        return (new ConfigurationUrlParser)
            ->parseConfiguration($config);
    }

    /**
     * Prepare the database connection instance.
     *
     * @param  \Illuminate\Database\Connection  $connection
     * @param  string  $type
     * @return \Illuminate\Database\Connection
     */
    protected function configure(Connection $connection, $type)
    {
        $connection = $this->setPdoForType($connection, $type)->setReadWriteType($type);

        // First we'll set the fetch mode and a few other dependencies of the database

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Add the missing connection to config/database.php under database.connections.{name}.
2. Verify the name passed to DB::connection() matches a configured key exactly (case, hyphens).
3. Run php artisan config:clear if you recently added the connection.
4. If the name is dynamic, register it via DatabaseManager::addConnection($name, $config) before resolving.

Example fix

// before
$conn = DB::connection('reporting'); // not configured -> throws

// after
// config/database.php
'connections' => [
    'reporting' => ['driver'=>'mysql','host'=>env('DB_REPORTING_HOST'), ...],
],
php artisan config:clear
DB::connection('reporting');

if (empty(config('database.connections.'.$name))) {
    throw new \RuntimeException("Database connection [$name] is not configured.");
}

function connectionConfigured(string $name): bool {
    return ! empty(config('database.connections.'.$name));
}

When it happens

Trigger: Calling DB::connection('reporting') when 'reporting' is not a key in database.connections; using an EnvEnum/string that doesn't map to a configured connection; passing a typo'd name from request input.

Common situations: DB_CONNECTION set to an undefined name; multi-tenant code resolving a tenant connection that wasn't bootstrapped; default connection name changed but config not updated; config:cache run before the connection was added.

Related errors

• Broadcast connection [{$name}] is not defined.
• Lost connection and no reconnector available.
• Database hosts array is empty.
• A driver must be specified.
• Unsupported driver [{$config['driver']}].

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/702263771570408f.json. Report an issue: GitHub.