laravel/framework · error · RuntimeException

Cannot establish connection [$name] because another…

Error message

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

What it means

Thrown by DatabaseManager::connectUsing() when a connection already exists under the given name and $force is false. connectUsing establishes an ad-hoc runtime connection; to avoid silently overwriting a live connection (and its open transactions/PDO handle), the manager requires explicit opt-in via the $force parameter or a prior purge().

Solutions

1. Pass $force=true: DB::connectUsing('analytics', $config, true) (it will purge the existing connection first).
2. Purge before reconnecting: DB::purge('analytics'); then DB::connectUsing('analytics', $config).
3. Use a unique name per runtime connection to avoid collisions.
4. Disconnect (DB::disconnect($name)) when the connection is no longer needed.

Example fix

// before
DB::connectUsing('tenant', $tenantConfig);
DB::connectUsing('tenant', $otherConfig);   // throws on second call

// after
DB::connectUsing('tenant', $otherConfig, true);   // force = purge + reconnect

if (isset($this->connections[$name]) && ! $force) {
    DB::purge($name);
}
DB::connectUsing($name, $config);

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

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

When it happens

Trigger: Calling DB::connectUsing('analytics', $config) twice in the same process without $force=true or a purge; calling connectUsing with a name that collides with a statically configured connection already opened; long-lived process (queue worker, daemon) re-establishing a runtime connection.

Common situations: Multi-tenant code that builds connections per tenant and reuses a name; queue workers that re-bind runtime connections across jobs; tests that call connectUsing repeatedly without resetting the manager.

Related errors

• Database connection [ ] not configured.
• A driver must be specified.
• Database file at path
• Database hosts array is empty.
• Database was not created. Aborting migration.

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

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