What causes "Unknown auth guard '{type}'" in phalcon/cphalcon?

Set type to a registered guard type, typically 'session' for the session guard

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

Unknown auth guard '{type}'

Error message

Unknown auth guard '{type}'

What it means

When ManagerFactory builds each guard, it reads the guard 'type' from config and looks it up in the GuardLocator. Only registered guard types (e.g. 'session', token-style guards, plus anything you registered yourself) are buildable; an unknown type throws UnknownGuard before the class's fromOptions() is called.

Source

Thrown at phalcon/Auth/ManagerFactory.zep:188

            isset(cfg["options"]) ? cfg["options"] : []
        );
    }

    /**
     * @param array<string, mixed> $options
     *
     * @throws Exception
     */
    protected function buildGuard(
        <GuardLocator> locator,
        string type,
        <Adapter> adapter,
        array options
    ) -> <Guard> {
        var className;

        if (!locator->has(type)) {
            throw new UnknownGuard(type);
        }

        let className = locator->getClass(type);

        return {className}::fromOptions(
            adapter,
            this->container,
            options
        );
    }

    /**
     * @return string
     */
    protected function getExceptionClass() -> string
    {
        return Exception::class;
    }

View on GitHub (pinned to b7419de9cd)

Solutions

Set type to a registered guard type, typically 'session' for the session guard
For custom guards, register the class on the GuardLocator (constructor argument of ManagerFactory) under your type name
Verify available types via the guard locator's known list before finalizing config

Example fix

// before
'type' => 'sessions',

// after
'type' => 'session',

Defensive patterns

Strategy: validation

Validate before calling

$knownTypes = array_keys($guardLocator->getAll());
if (!in_array($guardCfg['type'] ?? '', $knownTypes, true)) {
    throw new InvalidArgumentException("Unknown guard type; registered: " . implode(', ', $knownTypes));
}

Try / catch

try {
    $manager = (new ManagerFactory($hasher, $di))->load($config);
} catch (\Phalcon\Auth\Exceptions\UnknownGuard $e) {
    // message names the bad type; fix config or register the guard type on the locator
}

Prevention

Use the registered short type names (e.g. 'session') - not class FQCNs - in config
Register custom guard classes on a custom GuardLocator before use
Add a config lint that checks guard types against the locator's known list

When it happens

Trigger: guards.web.type set to an unregistered/misspelled value: 'sessions', 'Session', a guard class FQCN instead of the short type name, or a custom guard type whose class was never registered on the GuardLocator.

Common situations: Typos or wrong casing in the type key; assuming new guard types exist after an upgrade before checking the locator; custom guard implementations not wired via a custom GuardLocator passed to ManagerFactory.

Related errors

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