{"record":{"id":"80232f3c8d6a4a13","repo":"phalcon/cphalcon","slug":"unknown-auth-guard-type","errorCode":null,"errorMessage":"Unknown auth guard '{type}'","messagePattern":"Unknown auth guard '(.+?)'","errorType":"exception","errorClass":"Phalcon\\Auth\\Exceptions\\UnknownGuard","httpStatus":null,"severity":"error","filePath":"phalcon/Auth/ManagerFactory.zep","lineNumber":188,"sourceCode":"            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,\n        <Adapter> adapter,\n        array options\n    ) -> <Guard> {\n        var className;\n\n        if (!locator->has(type)) {\n            throw new UnknownGuard(type);\n        }\n\n        let className = locator->getClass(type);\n\n        return {className}::fromOptions(\n            adapter,\n            this->container,\n            options\n        );\n    }\n\n    /**\n     * @return string\n     */\n    protected function getExceptionClass() -> string\n    {\n        return Exception::class;\n    }","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Auth/ManagerFactory.zep#L170-L206","documentation":"When ManagerFactory builds each guard, it reads the guard 'type' from config and looks it up in the GuardLocator. Only registered guard types (e.g. 'session', token-style guards, plus anything you registered yourself) are buildable; an unknown type throws UnknownGuard before the class's fromOptions() is called.","triggerScenarios":"guards.web.type set to an unregistered/misspelled value: 'sessions', 'Session', a guard class FQCN instead of the short type name, or a custom guard type whose class was never registered on the GuardLocator.","commonSituations":"Typos or wrong casing in the type key; assuming new guard types exist after an upgrade before checking the locator; custom guard implementations not wired via a custom GuardLocator passed to ManagerFactory.","solutions":["Set type to a registered guard type, typically 'session' for the session guard","For custom guards, register the class on the GuardLocator (constructor argument of ManagerFactory) under your type name","Verify available types via the guard locator's known list before finalizing config"],"exampleFix":"// before\n'type' => 'sessions',\n\n// after\n'type' => 'session',","handlingStrategy":"validation","validationCode":"$knownTypes = array_keys($guardLocator->getAll());\nif (!in_array($guardCfg['type'] ?? '', $knownTypes, true)) {\n    throw new InvalidArgumentException(\"Unknown guard type; registered: \" . implode(', ', $knownTypes));\n}","typeGuard":null,"tryCatchPattern":"try {\n    $manager = (new ManagerFactory($hasher, $di))->load($config);\n} catch (\\Phalcon\\Auth\\Exceptions\\UnknownGuard $e) {\n    // message names the bad type; fix config or register the guard type on the locator\n}","preventionTips":["Use the registered short type names (e.g. 'session') - not class FQCNs - in config","Register custom guard classes on a custom GuardLocator before use","Add a config lint that checks guard types against the locator's known list"],"tags":["auth","guard","configuration","unknown-name"],"backgroundTag":"unregistered-guard-name","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}