phalcon/cphalcon · error · Phalcon\Auth\Exceptions\AccessNotRegistered

Access '{accessName}' is not registered

Error message

Access '{accessName}' is not registered

What it means

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.

Source

Thrown at phalcon/Auth/Manager.zep:59

    protected ?<Guard> defaultGuard = null;

    /**
     * @var array<string, Guard>
     */
    protected array guards = [];

    public function __construct(<AccessLocator> accessFactory)
    {
        let this->accessFactory = accessFactory;
    }

    /**
     * @throws Exception
     */
    public function access(string accessName) -> <self>
    {
        if (!this->accessFactory->has(accessName)) {
            throw new AccessNotRegistered(accessName);
        }

        let this->activeAccess = <Access> this->accessFactory->newInstance(accessName);

        return this;
    }

    /**
     * @phpstan-param array<string, class-string<Access>> $accessList
     */
    public function addAccessList(array accessList) -> <self>
    {
        var className, name;

        for name, className in accessList {
            this->accessFactory->register(name, className);
        }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Register the access component before use: $manager->addAccessList(['acl' => \App\Auth\Access\AclAccess::class]);
2. Match the key exactly (case-sensitive) between addAccessList()/config 'access' and the access() call
3. If loading from config, ensure the 'access' block is present and non-empty so ManagerFactory::load() registers it

Example fix

// before
$auth->access('acl')->allows('admin.area');

// after
$manager->addAccessList(['acl' => \App\Auth\Access\AclAccess::class]);
$auth->access('acl')->allows('admin.area');

if (!in_array('acl', array_keys($manager->getAccessList()), true)) {
    $manager->addAccessList(['acl' => \App\Auth\Access\AclAccess::class]);
}

try {
    $auth->access('acl')->allows('admin.area');
} catch (\Phalcon\Auth\Exceptions\AccessNotRegistered $e) {
    // register the access component once at bootstrap; rethrow as config error
}

When it happens

Trigger: $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.

Common situations: 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).

Related errors

• Access denied for {type} '{name}'
• The Acl access gate requires the 'handler' context key to de
• Authenticated user does not implement 'Phalcon\Acl\RoleAware
• No active access - call access() first
• Malformed ACL snapshot structure

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/eedddffab50c9926. Report an issue: GitHub.