{"record":{"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/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/DatabaseManager.php#L141-L177","documentation":"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().","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass $force=true: DB::connectUsing('analytics', $config, true) (it will purge the existing connection first).","Purge before reconnecting: DB::purge('analytics'); then DB::connectUsing('analytics', $config).","Use a unique name per runtime connection to avoid collisions.","Disconnect (DB::disconnect($name)) when the connection is no longer needed."],"exampleFix":"// before\nDB::connectUsing('tenant', $tenantConfig);\nDB::connectUsing('tenant', $otherConfig);   // throws on second call\n\n// after\nDB::connectUsing('tenant', $otherConfig, true);   // force = purge + reconnect","handlingStrategy":"validation","validationCode":"if (isset($this->connections[$name]) && ! $force) {\n    DB::purge($name);\n}\nDB::connectUsing($name, $config);","typeGuard":"function connectionNameIsFree(string $name): bool {\n    return ! array_key_exists($name, app('db')->getConnections());\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, true);\n    } else { throw $e; }\n}","preventionTips":["Pass $force=true or call DB::purge($name) before re-establishing a runtime connection.","Use unique names for ad-hoc connections (e.g. per-tenant identifiers).","Disconnect connections when no longer needed with DB::disconnect($name)."],"tags":["database","connection-manager","multi-tenant","laravel"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}