{"id":"db286ff2f01a8362","repo":"laravel/framework","slug":"cannot-establish-connection-name-because-anothe","errorCode":null,"errorMessage":"Cannot establish connection [$name] because another connection with that name already exists.","messagePattern":"Cannot establish connection \\[\\$name\\] because another connection with that name already exists\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/DatabaseManager.php","lineNumber":159,"sourceCode":"     * Get a database connection instance from the given configuration.\n     *\n     * @param  \\UnitEnum|string  $name\n     * @param  array  $config\n     * @param  bool  $force\n     * @return \\Illuminate\\Database\\ConnectionInterface\n     *\n     * @throws \\RuntimeException\n     */\n    public function connectUsing(UnitEnum|string $name, array $config, bool $force = false)\n    {\n        $name = enum_value($name);\n\n        if ($force) {\n            $this->purge($name);\n        }\n\n        if (isset($this->connections[$name])) {\n            throw new RuntimeException(\"Cannot establish connection [$name] because another connection with that name already exists.\");\n        }\n\n        $connection = $this->configure(\n            $this->factory->make($config, $name), null\n        );\n\n        $this->dispatchConnectionEstablishedEvent($connection);\n\n        return tap($connection, fn ($connection) => $this->connections[$name] = $connection);\n    }\n\n    /**\n     * Parse the connection into an array of the name and read / write type.\n     *\n     * @param  string  $name\n     * @return array\n     */\n    protected function parseConnectionName($name)","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Database/DatabaseManager.php#L141-L177","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass true as the third arg to force: DB::connectUsing($name, $config, force: true) (it purges the old one first).","Purge the existing connection before reconnecting: DB::purge($name); then connectUsing(...).","Use a unique connection name per logical tenant/instance to avoid collisions.","Prefer DB::addConnection() / config persistence for long-lived setups."],"exampleFix":"// before\nDB::connectUsing('tenant', $tenantConfig);\n// ... later, same call throws\n\n// after\nDB::purge('tenant');\nDB::connectUsing('tenant', $tenantConfig);\n// or\nDB::connectUsing('tenant', $tenantConfig, force: true);","handlingStrategy":"validation","validationCode":"if (isset(DB::getConnections()[$name])) {\n    DB::purge($name);\n}\nDB::connectUsing($name, $config);","typeGuard":"function connectionNameIsFree(string $name): bool {\n    return ! isset(app('db')->getConnections()[$name]);\n}","tryCatchPattern":"try {\n    DB::connectUsing($name, $config);\n} catch (\\RuntimeException $e) {\n    if (str_contains($e->getMessage(), 'already exists')) {\n        DB::connectUsing($name, $config, force: true);\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Use unique connection names per tenant/instance.","Pass force: true when re-establishing a known-existing connection.","Purge stale connections before reconnecting.","Prefer DatabaseManager::addConnection + config persistence for stable setups."],"tags":["connection","multi-tenant","runtime-config"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}