{"record":{"id":"cd8f39c10112843d","repo":"phalcon/cphalcon","slug":"unknown-auth-adapter-name","errorCode":null,"errorMessage":"Unknown auth adapter '{name}'","messagePattern":"Unknown auth adapter '(.+?)'","errorType":"exception","errorClass":"Phalcon\\Auth\\Exceptions\\UnknownAdapter","httpStatus":null,"severity":"error","filePath":"phalcon/Auth/ManagerFactory.zep","lineNumber":163,"sourceCode":"            manager->addAccessList(accessList);\n        }\n\n        return manager;\n    }\n\n    /**\n     * @param array{name: string, options?: array<string, mixed>} $cfg\n     *\n     * @throws Exception\n     */\n    protected function buildAdapter(<AdapterLocator> locator, array cfg) -> <Adapter>\n    {\n        var className, name;\n\n        let name = Options::requireString(cfg, \"name\", \"adapter\");\n\n        if (!locator->has(name)) {\n            throw new UnknownAdapter(name);\n        }\n\n        let className = locator->getClass(name);\n\n        return {className}::fromOptions(\n            this->hasher,\n            isset(cfg[\"options\"]) ? cfg[\"options\"] : []\n        );\n    }\n\n    /**\n     * @param array<string, mixed> $options\n     *\n     * @throws Exception\n     */\n    protected function buildGuard(\n        <GuardLocator> locator,\n        string type,","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Auth/ManagerFactory.zep#L145-L181","documentation":"When ManagerFactory builds each guard's adapter, it reads the adapter 'name' from config (Options::requireString) and looks it up in the AdapterLocator. The locator only knows the built-in/registered adapters (e.g. 'stream', 'model'); an unknown name throws UnknownAdapter before any class is instantiated.","triggerScenarios":"guards.web.adapter.name set to a value never registered on the AdapterLocator: a typo ('streem'), a fully-qualified class name where a short locator name is expected, or a custom adapter class that was never registered on the locator.","commonSituations":"Writing adapter: {name: \\App\\Auth\\MyAdapter::class} assuming FQCNs are accepted; typos in config; upgrading to a version that renamed adapter keys; forgetting to pass a custom AdapterLocator carrying your own adapters to ManagerFactory.","solutions":["Use the exact registered adapter name, e.g. 'stream' or 'model', in the adapter config","For a custom adapter, register it on the AdapterLocator you pass to ManagerFactory, then reference that name","Check spelling/case of the adapter name against the locator's known list (locator->has(name) / getAll())"],"exampleFix":"// before\n'adapter' => ['name' => 'Streem'],\n\n// after\n'adapter' => ['name' => 'stream'],","handlingStrategy":"validation","validationCode":"$knownAdapters = array_keys($adapterLocator->getAll());\nif (!in_array($cfg['name'] ?? '', $knownAdapters, true)) {\n    throw new InvalidArgumentException(\"Unknown adapter; registered: \" . implode(', ', $knownAdapters));\n}","typeGuard":null,"tryCatchPattern":"try {\n    $manager = (new ManagerFactory($hasher, $di))->load($config);\n} catch (\\Phalcon\\Auth\\Exceptions\\UnknownAdapter $e) {\n    // message names the bad adapter; fix config or register the adapter on the locator\n}","preventionTips":["Use only registered adapter names ('stream', 'model', or your own registered ones) in config","Register custom adapters on a custom AdapterLocator passed to ManagerFactory","Validate config adapter names against the locator at boot"],"tags":["auth","adapter","configuration","unknown-name"],"backgroundTag":"unregistered-adapter-name","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}