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

Authenticated user does not implement 'Phalcon\Acl\RoleAware

Error message

Authenticated user does not implement 'Phalcon\Acl\RoleAwareInterface'

What it means

To run an ACL check the Acl access gate needs the authenticated user's role, obtained by calling getRoleName() from Phalcon\Acl\RoleAwareInterface on the guard's user object (a null user maps to the configured guest role). If the returned user implements neither the interface nor null, the gate throws DoesNotImplement naming 'Authenticated user' and the interface.

Source

Thrown at phalcon/Auth/Access/Acl.zep:133

    /**
     * @throws Exception
     */
    protected function resolveRole(<Guard> guard) -> string
    {
        var user;

        let user = guard->user();

        if (user === null) {
            return this->guestRole;
        }

        if (user instanceof RoleAwareInterface) {
            return user->getRoleName();
        }

        throw new DoesNotImplement(
            "Authenticated user",
            RoleAwareInterface::class
        );
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Implement the interface on your user class: `public function getRoleName(): string { return $this->role; }`
2. Make sure the guard actually returns that class (and null when unauthenticated, which resolves to guestRole)
3. If you cannot change the model, wrap the user in a small RoleAware decorator before it reaches the guard

Example fix

// before
class User extends Model {}
// after
class User extends Model implements \Phalcon\Acl\RoleAwareInterface
{
    public function getRoleName(): string
    {
        return $this->role; // e.g. 'admins'
    }
}

if ($guard->user() !== null && !$guard->user() instanceof \Phalcon\Acl\RoleAwareInterface) {
    throw new InvalidArgumentException('User class must implement RoleAwareInterface to use the Acl gate');
}

function isRoleAwareUser(mixed $user): bool
{
    return $user === null || $user instanceof \Phalcon\Acl\RoleAwareInterface;
}

try {
    $allowed = $access->isAllowed($guard, $actionName, $context);
} catch (\Phalcon\Auth\Exceptions\DoesNotImplement $e) {
    $logger->error('Auth user model lacks RoleAwareInterface: ' . $e->getMessage());
    throw $e;
}

When it happens

Trigger: The auth guard returns a logged-in user object that is not an instance of Phalcon\Acl\RoleAwareInterface — e.g. an entity from a custom user provider, a stdClass/array-based user, or a third-party identity class — on the first access check.

Common situations: Plugging an existing user model into the new Auth component without adding the interface; a guard whose user() returns a DTO; partially migrated codebases where only some user classes were adapted.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Access denied for {type} '{name}'
• The Acl access gate requires the 'handler' context key to de
• AuthUser data must contain a scalar 'id' key (int|string)
• Access '{accessName}' is not registered
• Malformed ACL snapshot structure

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