laravel/framework · error · UnexpectedValueException

Invalid database connection

Error message

Invalid database connection [{$db}].

What it means

Thrown by DbCommand::getConnection() (the artisan `db` console command) when the resolved connection config is empty. It looks up database.connections.<name> using the command argument or the default connection; if that entry is absent or empty, the command cannot build a PDO config and aborts.

Solutions

1. Add the connection to config/database.php under database.connections.<name> with a valid driver.
2. Verify the name passed to `artisan db` matches a configured connection key exactly.
3. Ensure database.default is set to an existing connection (DB_CONNECTION).
4. Clear the config cache if you recently edited config: php artisan config:clear.

Example fix

// before
php artisan db readreplica   # not in config

// after
// config/database.php: add 'readreplica' => [...]
php artisan db readreplica

$name = $requestedName ?? config('database.default');
if (empty(config('database.connections.'.$name))) {
    throw new \UnexpectedValueException("Connection '{$name}' is not configured.");
}

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

When it happens

Trigger: Running `php artisan db foo` where 'foo' is not defined in database.connections; running `php artisan db` with database.default pointing at an undefined connection; the connection config resolves to null because .env vars are unset.

Common situations: Typo in the connection name argument; referencing an environment-specific connection that is not present in the current config; misconfigured database.default; stale config cache (php artisan config:cache) baked in before the connection was added.

Related errors

• Database was not created. Aborting migration.
• The --model and --except options cannot be combined.
• A driver must be specified.
• Database connection [ ] not configured.
• Database file at path

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

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