laravel/framework · error · UnexpectedValueException

Invalid database connection [{$db}].

Error message

Invalid database connection [{$db}].

What it means

Thrown by DbCommand::getConnection() (the artisan db / db:show / db:table / db:wipe console command base) when the connection name argument (or the configured default) resolves to an empty config array. The command refuses to launch the DB client against an unknown connection.

Source

Thrown at src/Illuminate/Database/Console/DbCommand.php:85

        return self::SUCCESS;
    }

    /**
     * Get the database connection configuration.
     *
     * @return array
     *
     * @throws \UnexpectedValueException
     */
    public function getConnection()
    {
        $connection = $this->laravel['config']['database.connections.'.
            (($db = $this->argument('connection')) ?? $this->laravel['config']['database.default'])
        ];

        if (empty($connection)) {
            throw new UnexpectedValueException("Invalid database connection [{$db}].");
        }

        if (! empty($connection['url'])) {
            $connection = (new ConfigurationUrlParser)->parseConfiguration($connection);
        }

        if ($this->option('read')) {
            $connection = $this->mergeConnectionConfiguration($connection, 'read');
        } elseif ($this->option('write')) {
            $connection = $this->mergeConnectionConfiguration($connection, 'write');
        } elseif (! $this->option('pooled') && ($connection['driver'] ?? null) === 'pgsql' && ($connection['pooled'] ?? false) === true && ! empty($connection['direct'])) {
            $connection = $this->mergeConnectionConfiguration($connection, 'direct');
        }

        return $connection;
    }

    /**

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Check the connection name is listed under database.connections in config/database.php.
2. Verify database.default is set to a defined connection when not passing an argument.
3. Run php artisan config:clear so a recently added connection is picked up.
4. List configured connections: php artisan db:show --counts or inspect config('database.connections').

Example fix

// before
php artisan db replica
// where 'replica' is not in database.connections

// after
// add to config/database.php:
'connections' => [
    'replica' => ['driver'=>'mysql','host'=>env('DB_REPLICA_HOST'), ...],
],
php artisan config:clear
php artisan db replica

$name = $request->input('connection', config('database.default'));
if (empty(config('database.connections.'.$name))) {
    abort(400, "Unknown database connection [$name].");
}

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

When it happens

Trigger: Running `php artisan db myconn` (or db:show / db:table / db:wipe with --database=myconn) where 'database.connections.myconn' is not defined or is empty. Also fires when database.default points at an undefined connection and no argument is given.

Common situations: Typo in the connection name passed to --database; connection defined in a separate config file that wasn't merged; database.default misconfigured; 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/2500ac282ca11f8c.json. Report an issue: GitHub.