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

Cannot resolve a fresh '{name}': it is not registered in the

Error message

Cannot resolve a fresh '{name}': it is not registered in the Di and is not an existing class

What it means

On the legacy Di branch of ContainerResolver::resolveFresh(), a name that is neither registered in the DI nor an existing (autoloadable) class cannot be built fresh, so a ContainerException is thrown. The Di's class builder can construct unregistered classes, but only when class_exists($name) is true - a typo or a missing import makes both checks fail.

Source

Thrown at phalcon/Auth/Internal/ContainerResolver.zep:127

    public static function resolveFresh(var container, string name) -> object
    {
        var e;

        self::ensureContainer(container);

        if (container instanceof Collection) {
            if (true !== container->has(name)) {
                throw new ContainerException(
                    "Cannot resolve a fresh '" . name
                    . "': it is not bound in the container"
                );
            }

            return container->{"new"}(name);
        }

        if (true !== container->has(name) && !class_exists(name)) {
            throw new ContainerException(
                "Cannot resolve a fresh '" . name
                . "': it is not registered in the Di and is not an existing class"
            );
        }

        try {
            return container->get(name);
        } catch DiException, e {
            throw new ContainerException(
                "Failed to resolve '" . name . "' from the Di container",
                0,
                e
            );
        }
    }

    /**
     * Builds the ordered candidate list for a framework service:

View on GitHub (pinned to b7419de9cd)

Solutions

1. Fix the class name string (typo, namespace, casing) so class_exists() returns true
2. Or explicitly register the service in the DI: $di->set($name, $definition)
3. Run composer dump-autoload / verify the PSR-4 mapping if the class exists on disk but does not autoload

Example fix

// before
$cfg = ['adapter' => ['name' => 'Phalcon\\Auth\\Adapter\\Streem']];

// after
$cfg = ['adapter' => ['name' => 'Phalcon\\Auth\\Adapter\\Stream']];

if (!$di->has($name) && !class_exists($name)) {
    throw new RuntimeException("'{$name}' is neither registered in DI nor an existing class");
}

try {
    $instance = $di->get($name);
} catch (\Phalcon\Container\Exceptions\Exception $e) {
    if (!class_exists($name)) {
        // class-name typo: fail loudly with a clear message
    }
}

When it happens

Trigger: resolveFresh($di, 'Phalcon\Auth\Adapter\Streem') with a misspelled class name; resolving a guard/adapter name that was never $di->set() and whose class does not exist (not autoloaded, wrong namespace, missing use statement).

Common situations: Typo in a class-string taken from config; class moved or renamed between versions so autoloading fails; config referencing a class in a namespace that was never imported/rewritten during an upgrade.

Related errors

• The parameter must be an instance of Collection or DiInterfa
• Auth {context} requires service. None of the following are b
• Cannot resolve a fresh '{name}': it is not bound in the cont
• Failed to resolve '{name}' from the Di container
• Unknown service type in parameter on position {}

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