laravel/framework · error · InvalidArgumentException

Database connection [ ] not configured.

Error message

Database connection [{$name}] not configured.

What it means

Thrown by DatabaseManager::configuration() when neither the static config (database.connections.<name>) nor the dynamicConnectionConfigurations map contains an entry for the requested name. Every other operation (opening, purging, configuring a connection) needs the config array, so a null result is rejected early with the offending name.

Solutions

1. Add the connection to config/database.php under database.connections.<name>.
2. If it is a runtime connection, register it first: DB::addConnection($name, $config) (or config()->set('database.connections.<name>', $config)) before calling DB::connection($name).
3. Check the exact name spelling and the value of database.default.
4. Clear the config cache after editing config: php artisan config:clear.

Example fix

// before
DB::connection('reporting')->table('sales')->get();   // not configured

// after
config(['database.connections.reporting' => ['driver' => 'pgsql', 'host' => '...', ...]]);
DB::connection('reporting')->table('sales')->get();

if (is_null(config("database.connections.{$name}"))
    && ! array_key_exists($name, app('db')->getConnections())) {
    throw new \InvalidArgumentException("Connection '{$name}' is not configured.");
}

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

When it happens

Trigger: Calling DB::connection('reporting') when 'reporting' is not in database.connections and was not added via DB::addConnection($name, $config); referencing a connection name in a model's $connection property that is not configured.

Common situations: Typo in the connection name; env-specific connection missing from current config; stale config cache; referencing a read/write connection suffix that does not exist; multi-tenant code calling DB::connection($tenant) before registering it.

Related errors

• A driver must be specified.
• Cannot establish connection [$name] because another…
• Database file at path
• Database hosts array is empty.
• Invalid database connection

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

Appendix: 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 e0f6eb3518)