laravel/framework · error · RuntimeException

Cannot establish connection [$name] because another connecti

Error message

Cannot establish connection [$name] because another connection with that name already exists.

What it means

Thrown by DatabaseManager::connectUsing() when you try to establish a runtime connection under a name that is already present in the manager's connections pool (and $force was not passed). It prevents silently replacing a live connection.

Source

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

     * Get a database connection instance from the given configuration.
     *
     * @param  \UnitEnum|string  $name
     * @param  array  $config
     * @param  bool  $force
     * @return \Illuminate\Database\ConnectionInterface
     *
     * @throws \RuntimeException
     */
    public function connectUsing(UnitEnum|string $name, array $config, bool $force = false)
    {
        $name = enum_value($name);

        if ($force) {
            $this->purge($name);
        }

        if (isset($this->connections[$name])) {
            throw new RuntimeException("Cannot establish connection [$name] because another connection with that name already exists.");
        }

        $connection = $this->configure(
            $this->factory->make($config, $name), null
        );

        $this->dispatchConnectionEstablishedEvent($connection);

        return tap($connection, fn ($connection) => $this->connections[$name] = $connection);
    }

    /**
     * Parse the connection into an array of the name and read / write type.
     *
     * @param  string  $name
     * @return array
     */
    protected function parseConnectionName($name)

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Pass true as the third arg to force: DB::connectUsing($name, $config, force: true) (it purges the old one first).
2. Purge the existing connection before reconnecting: DB::purge($name); then connectUsing(...).
3. Use a unique connection name per logical tenant/instance to avoid collisions.
4. Prefer DB::addConnection() / config persistence for long-lived setups.

Example fix

// before
DB::connectUsing('tenant', $tenantConfig);
// ... later, same call throws

// after
DB::purge('tenant');
DB::connectUsing('tenant', $tenantConfig);
// or
DB::connectUsing('tenant', $tenantConfig, force: true);

if (isset(DB::getConnections()[$name])) {
    DB::purge($name);
}
DB::connectUsing($name, $config);

function connectionNameIsFree(string $name): bool {
    return ! isset(app('db')->getConnections()[$name]);
}

try {
    DB::connectUsing($name, $config);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'already exists')) {
        DB::connectUsing($name, $config, force: true);
    } else {
        throw $e;
    }
}

When it happens

Trigger: Calling DB::connectUsing('analytics', $config) twice without the third $force argument; or calling connectUsing with a name that collides with an already-resolved standard connection.

Common situations: Multi-tenant code that builds per-tenant connections dynamically and reuses a tenant id twice; reconnecting to the same alias after a config change without purging; a loop that calls connectUsing on every request.

Related errors

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

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