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

Unknown auth adapter '{name}'

Error message

Unknown auth adapter '{name}'

What it means

When ManagerFactory builds each guard's adapter, it reads the adapter 'name' from config (Options::requireString) and looks it up in the AdapterLocator. The locator only knows the built-in/registered adapters (e.g. 'stream', 'model'); an unknown name throws UnknownAdapter before any class is instantiated.

Source

Thrown at phalcon/Auth/ManagerFactory.zep:163

            manager->addAccessList(accessList);
        }

        return manager;
    }

    /**
     * @param array{name: string, options?: array<string, mixed>} $cfg
     *
     * @throws Exception
     */
    protected function buildAdapter(<AdapterLocator> locator, array cfg) -> <Adapter>
    {
        var className, name;

        let name = Options::requireString(cfg, "name", "adapter");

        if (!locator->has(name)) {
            throw new UnknownAdapter(name);
        }

        let className = locator->getClass(name);

        return {className}::fromOptions(
            this->hasher,
            isset(cfg["options"]) ? cfg["options"] : []
        );
    }

    /**
     * @param array<string, mixed> $options
     *
     * @throws Exception
     */
    protected function buildGuard(
        <GuardLocator> locator,
        string type,

View on GitHub (pinned to b7419de9cd)

Solutions

1. Use the exact registered adapter name, e.g. 'stream' or 'model', in the adapter config
2. For a custom adapter, register it on the AdapterLocator you pass to ManagerFactory, then reference that name
3. Check spelling/case of the adapter name against the locator's known list (locator->has(name) / getAll())

Example fix

// before
'adapter' => ['name' => 'Streem'],

// after
'adapter' => ['name' => 'stream'],

$knownAdapters = array_keys($adapterLocator->getAll());
if (!in_array($cfg['name'] ?? '', $knownAdapters, true)) {
    throw new InvalidArgumentException("Unknown adapter; registered: " . implode(', ', $knownAdapters));
}

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

When it happens

Trigger: guards.web.adapter.name set to a value never registered on the AdapterLocator: a typo ('streem'), a fully-qualified class name where a short locator name is expected, or a custom adapter class that was never registered on the locator.

Common situations: Writing adapter: {name: \App\Auth\MyAdapter::class} assuming FQCNs are accepted; typos in config; upgrading to a version that renamed adapter keys; forgetting to pass a custom AdapterLocator carrying your own adapters to ManagerFactory.

Related errors

• Auth guard '{name}' is not defined
• Unknown auth guard '{type}'
• Malformed ACL snapshot structure
• Stream adapter file does not exist: {path}
• Stream adapter file is not valid JSON: {path}

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