What causes "Auth guard '{name}' is not defined" in phalcon/cphalcon?

Add the guard to your auth config under the exact name used in code, with its adapter and type

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

Auth guard ' ' 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.

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

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

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

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

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

Appendix: 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)