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

Auth guard '{name}' is not defined

Error message

Auth guard '{name}' is not defined

What it means

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.

Source

Thrown at phalcon/Auth/Manager.zep:160

    {
        return this->guards;
    }

    /**
     * @throws Exception
     */
    public function guard(string name = null) -> <Guard>
    {
        if (name === null) {
            if (this->defaultGuard === null) {
                throw new DefaultGuardNotRegistered();
            }

            return this->defaultGuard;
        }

        if (!isset(this->guards[name])) {
            throw new GuardNotDefined(name);
        }

        return this->guards[name];
    }

    public function id() -> int | string | null
    {
        return this->guard()->id();
    }

    public function logout() -> void
    {
        this->requireStatefulGuard()->logout();
    }

    /**
     * @throws Exception
     */

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add the guard to your auth config under the exact name used in code, with its adapter and type
2. Or register it programmatically: $manager->addGuard('api', $guard)
3. Align naming: dump the configured guards with $manager->getGuards() and compare keys against the name you pass

Example fix

// before
$auth->guard('api')->attempt($credentials);
// config has only 'web'

// after
'guards' => [
    'web' => [...],
    'api' => [
        'adapter' => ['name' => 'stream', 'options' => [...]],
        'type' => 'token',
    ],
],

$knownGuards = array_keys($manager->getGuards());
if (!in_array('api', $knownGuards, true)) {
    throw new InvalidArgumentException("guard 'api' is not defined; known: " . implode(', ', $knownGuards));
}

try {
    $guard = $auth->guard('api');
} catch (\Phalcon\Auth\Exceptions\GuardNotDefined $e) {
    // message names the missing guard; add it to config or fix the name
}

When it happens

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

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

Related errors

• Unknown auth guard '{type}'
• Session guard 'name' and 'rememberName' must differ
• No default guard registered
• Unknown auth adapter '{name}'
• Malformed ACL snapshot structure

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