{"record":{"id":"ca190f2dd60b8bf3","repo":"phalcon/cphalcon","slug":"auth-guard-name-is-not-defined","errorCode":null,"errorMessage":"Auth guard '{name}' is not defined","messagePattern":"Auth guard '(.+?)' is not defined","errorType":"exception","errorClass":"Phalcon\\Auth\\Exceptions\\GuardNotDefined","httpStatus":null,"severity":"error","filePath":"phalcon/Auth/Manager.zep","lineNumber":160,"sourceCode":"    {\n        return this->guards;\n    }\n\n    /**\n     * @throws Exception\n     */\n    public function guard(string name = null) -> <Guard>\n    {\n        if (name === null) {\n            if (this->defaultGuard === null) {\n                throw new DefaultGuardNotRegistered();\n            }\n\n            return this->defaultGuard;\n        }\n\n        if (!isset(this->guards[name])) {\n            throw new GuardNotDefined(name);\n        }\n\n        return this->guards[name];\n    }\n\n    public function id() -> int | string | null\n    {\n        return this->guard()->id();\n    }\n\n    public function logout() -> void\n    {\n        this->requireStatefulGuard()->logout();\n    }\n\n    /**\n     * @throws Exception\n     */","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Auth/Manager.zep#L142-L178","documentation":"Manager::guard(name) looks up a guard by name in the registry populated by addGuard()/ManagerFactory::load(). An unknown name throws GuardNotDefined. This is the named counterpart of error 52: the name you asked for was never registered, regardless of whether a default exists.","triggerScenarios":"$auth->guard('api') when config only defines 'web'; case or spelling mismatch ('Web', 'Api' vs 'api'); calling guard('web') before ManagerFactory::load() registered anything; guards defined in a different config file that was never loaded.","commonSituations":"Adding a second guard to code but not to the auth config; renaming a guard key in config without updating call sites (or vice versa); environment-specific config files that drift (local defines 'api', production does not).","solutions":["Add the guard to your auth config under the exact name used in code, with its adapter and type","Or register it programmatically: $manager->addGuard('api', $guard)","Align naming: dump the configured guards with $manager->getGuards() and compare keys against the name you pass"],"exampleFix":"// before\n$auth->guard('api')->attempt($credentials);\n// config has only 'web'\n\n// after\n'guards' => [\n    'web' => [...],\n    'api' => [\n        'adapter' => ['name' => 'stream', 'options' => [...]],\n        'type' => 'token',\n    ],\n],","handlingStrategy":"validation","validationCode":"$knownGuards = array_keys($manager->getGuards());\nif (!in_array('api', $knownGuards, true)) {\n    throw new InvalidArgumentException(\"guard 'api' is not defined; known: \" . implode(', ', $knownGuards));\n}","typeGuard":null,"tryCatchPattern":"try {\n    $guard = $auth->guard('api');\n} catch (\\Phalcon\\Auth\\Exceptions\\GuardNotDefined $e) {\n    // message names the missing guard; add it to config or fix the name\n}","preventionTips":["Define guard names once (constants/config schema) and reference them everywhere","Diff guard keys between config environments during deploy checks","Log getGuards() keys at boot to catch config drift early"],"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"}