What causes "Circular alias detected: '{name}'" in phalcon/cphalcon?

Rebuild the alias map from scratch: clear aliases and re-register each one via setAlias() so cycle detection runs again

phalcon/cphalcon · error · Phalcon\Container\Exceptions\CircularAliasFound

Circular alias detected: '{name}'

Error message

Circular alias detected: '{name}'

What it means

resolveAlias() follows the alias map until it reaches a key that is not itself an alias, tracking visited keys; CircularAliasFound is thrown at resolution time when a key repeats. setAlias() normally prevents cycles at registration, so encountering this during get()/has() means the alias map was modified outside that guard or the container state got corrupted.

Source

Thrown at phalcon/Container/Container.zep:765

    /**
     * Resolve an alias
     *
     * @param string $name
     *
     * @return string
     * @throws CircularAliasFound
     */
    private function resolveAlias(string name) -> string
    {
        var seen, current;

        let seen    = [];
        let current = name;

        while (array_key_exists(current, this->aliases)) {
            if (array_key_exists(current, seen)) {
                throw new CircularAliasFound(name);
            }

            let seen[current] = true;
            let current       = this->aliases[current];
        }

        return current;
    }

    /**
     * Resolve a paramater
     *
     * @param string $name
     *
     * @return mixed
     */
    private function resolveParameter(string name) -> mixed
    {

View on GitHub (pinned to b7419de9cd)

Solutions

Rebuild the alias map from scratch: clear aliases and re-register each one via setAlias() so cycle detection runs again
Audit any code that writes to the alias map directly and route all changes through setAlias()
Invalidate any cached/serialized container after alias changes instead of reusing stale state
Catch CircularAliasFound during boot and fail fast, logging the alias chain for diagnosis

Example fix

// before
$container->aliases = ['db' => 'database', 'database' => 'db']; // bypasses guard
$container->get('db'); // CircularAliasFound

// after
$container->set('db', Connection::class);
$container->setAlias('db', 'database');

Defensive patterns

Strategy: try-catch

Try / catch

use Phalcon\Container\Exceptions\CircularAliasFound;

try {
    $service = $container->get('db');
} catch (CircularAliasFound $e) {
    // alias map is inconsistent: rebuild aliases via setAlias() from a known-good table
    throw new LogicException('Corrupt alias map, rebuild container aliases', 0, $e);
}

Prevention

Never write to the alias map directly; always go through setAlias()
Do not cache/serialize containers across alias changes — invalidate instead
Register aliases once at boot from a declarative config so the guard in setAlias() always runs

When it happens

Trigger: A custom Container subclass or serialized/cached container writing to the alias array directly; a cache/serialization round-trip that restored inconsistent alias state; runtime alias registration racing in long-running workers.

Common situations: Container snapshots cached between requests; plugins registering aliases at runtime; state restored from sleep/wakeup or a cache backend.

Related errors

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