{"record":{"id":"eedddffab50c9926","repo":"phalcon/cphalcon","slug":"access-accessname-is-not-registered","errorCode":null,"errorMessage":"Access '{accessName}' is not registered","messagePattern":"Access '(.+?)' is not registered","errorType":"exception","errorClass":"Phalcon\\Auth\\Exceptions\\AccessNotRegistered","httpStatus":null,"severity":"error","filePath":"phalcon/Auth/Manager.zep","lineNumber":59,"sourceCode":"    protected ?<Guard> defaultGuard = null;\n\n    /**\n     * @var array<string, Guard>\n     */\n    protected array guards = [];\n\n    public function __construct(<AccessLocator> accessFactory)\n    {\n        let this->accessFactory = accessFactory;\n    }\n\n    /**\n     * @throws Exception\n     */\n    public function access(string accessName) -> <self>\n    {\n        if (!this->accessFactory->has(accessName)) {\n            throw new AccessNotRegistered(accessName);\n        }\n\n        let this->activeAccess = <Access> this->accessFactory->newInstance(accessName);\n\n        return this;\n    }\n\n    /**\n     * @phpstan-param array<string, class-string<Access>> $accessList\n     */\n    public function addAccessList(array accessList) -> <self>\n    {\n        var className, name;\n\n        for name, className in accessList {\n            this->accessFactory->register(name, className);\n        }\n","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Auth/Manager.zep#L41-L77","documentation":"The Auth Manager is also a fluent front-end for access-control (ACL-style) checks: you select an access component with $auth->access('name'), and every subsequent access call on the manager delegates to it. Before switching, Manager::access() verifies the name was registered on the AccessLocator; if not, it throws AccessNotRegistered. Registration happens via Manager::addAccessList(['acl' => AclAccess::class, ...]) or the 'access' block of the config loaded by ManagerFactory.","triggerScenarios":"$auth->access('acl')->allows(...) before any addAccessList() call; using a name that differs from the registered key (case-sensitive), e.g. access('ACL') when 'acl' was registered; config loaded without an 'access' section.","commonSituations":"Calling access checks in a controller before the auth config's access section is wired; renaming access keys in config while call sites keep the old name; per-module access lists registered only after first use (ordering bug in bootstrap).","solutions":["Register the access component before use: $manager->addAccessList(['acl' => \\App\\Auth\\Access\\AclAccess::class]);","Match the key exactly (case-sensitive) between addAccessList()/config 'access' and the access() call","If loading from config, ensure the 'access' block is present and non-empty so ManagerFactory::load() registers it"],"exampleFix":"// before\n$auth->access('acl')->allows('admin.area');\n\n// after\n$manager->addAccessList(['acl' => \\App\\Auth\\Access\\AclAccess::class]);\n$auth->access('acl')->allows('admin.area');","handlingStrategy":"validation","validationCode":"if (!in_array('acl', array_keys($manager->getAccessList()), true)) {\n    $manager->addAccessList(['acl' => \\App\\Auth\\Access\\AclAccess::class]);\n}","typeGuard":null,"tryCatchPattern":"try {\n    $auth->access('acl')->allows('admin.area');\n} catch (\\Phalcon\\Auth\\Exceptions\\AccessNotRegistered $e) {\n    // register the access component once at bootstrap; rethrow as config error\n}","preventionTips":["Register access components in the same bootstrap that builds the auth manager","Keep access keys as constants shared between config and call sites","Cover first-use ordering with a boot test that performs one access check"],"tags":["auth","access-control","acl","registration"],"backgroundTag":"authorization-not-configured","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}