{"record":{"id":"6cf2847237bf78d5","repo":"phalcon/cphalcon","slug":"connection-not-found-type-requested","errorCode":null,"errorMessage":"Connection not found: {type}:{requested}","messagePattern":"Connection not found: (.+?):(.+?)","errorType":"exception","errorClass":"Phalcon\\DataMapper\\Pdo\\Exception\\ConnectionNotFound","httpStatus":null,"severity":"error","filePath":"phalcon/DataMapper/Pdo/ConnectionLocator.zep","lineNumber":212,"sourceCode":"        /**\n         * No collection returns the master\n         */\n        if empty collection {\n            return this->getMaster();\n        }\n\n        /**\n         * If the requested name is empty, get a random connection\n         */\n        if \"\" === requested {\n            let requested = array_rand(collection);\n        }\n\n        /**\n         * If the connection name does not exist, send an exception back\n         */\n        if !isset collection[requested] {\n            throw new ConnectionNotFound(\n                \"Connection not found: \" . type . \":\" . requested\n            );\n        }\n\n        /**\n         * Check if the connection has been resolved already, if yes return\n         * it, otherwise resolve it. The keys in the `resolved` array are\n         * formatted as \"type-name\"\n         */\n        let instanceName = type . \"-\" . requested;\n\n        if !isset instances[instanceName] {\n            let instances[instanceName] = call_user_func(collection[requested]),\n                this->instances         = instances;\n        }\n\n        return this->applyEventsManager(instances[instanceName]);\n    }","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/DataMapper/Pdo/ConnectionLocator.zep#L194-L230","documentation":"ConnectionLocator stores named connection factories per role (read, write, plus a 'default'). When the requested name is absent from that role's collection it throws ConnectionNotFound with 'type:name'. An empty requested name selects a random entry — but only from a non-empty collection, so a role with no configured factories also fails.","triggerScenarios":"$locator->getRead('slave2') when only 'slave1' or nothing was registered with setRead(); a typo or config/code naming mismatch (slave vs replica); getWrite() when only read factories were configured; requesting 'default' after the default factory was never set.","commonSituations":"Replica config keys not matching the names code requests; environments without replicas where no fallback default was registered; dynamically computed shard/replica names at runtime.","solutions":["Register the name before use: $locator->setRead('slave2', $factory)","Validate requested names against a known-names list from config before calling getRead()/getWrite()","Ensure each role has at least one entry (typically 'default') so empty-string random selection has something to pick","Centralize connection names in one config array/constants to prevent drift between config and code"],"exampleFix":"// before\n$conn = $locator->getRead('slave2'); // ConnectionNotFound: read:slave2\n\n// after\n$locator->setRead('slave2', function () use ($dsn2) {\n    return new \\Phalcon\\DataMapper\\Pdo\\Connection($dsn2, 'user', 'pass');\n});\n$conn = $locator->getRead('slave2');","handlingStrategy":"validation","validationCode":"// Validate against the configured replica names before lookup\n$readReplicas = array_keys($config->get('database.replicas'));\nif ($name !== '' && !in_array($name, $readReplicas, true)) {\n    throw new InvalidArgumentException(\n        \"Unknown read connection '{$name}'; configured: \" . implode(', ', $readReplicas)\n    );\n}\n$conn = $locator->getRead($name);","typeGuard":null,"tryCatchPattern":"use Phalcon\\DataMapper\\Pdo\\Exception\\ConnectionNotFound;\n\ntry {\n    $conn = $locator->getRead($name);\n} catch (ConnectionNotFound $e) {\n    $conn = $locator->getRead('default'); // fall back to the default read connection\n}","preventionTips":["Always configure a 'default' factory for each role so fallback exists","Derive requested connection names from the same config that registers them — never hardcode separately","Guard dynamic names (shards, replicas) with a known-names check before getRead()/getWrite()"],"tags":["pdo","database","connection-locator","read-write-split","phalcon"],"backgroundTag":"named-connection-missing","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}