What causes "Failed to resolve '{name}' from the Di container" in phalcon/cphalcon?

Inspect the chained cause: catch the ContainerException and read getPrevious() - the real failure is the inner exception

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

Failed to resolve '{name}' from the Di container

Error message

Failed to resolve '{name}' from the Di container

What it means

On the legacy Di path of resolveFresh(), the service name passes the pre-checks (registered or existing class), but the actual $container->get($name) call throws a DiException - for example the factory/closure bound to that key raised an error, a constructor dependency could not be resolved, or a circular dependency was detected. The resolver normalizes this to Phalcon\Container\Exceptions\Exception (ContainerException) with the original DiException chained as previous, so userland catches a single exception family.

Source

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

                    "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:
     * an explicit override from options['services'][key] if present,
     * otherwise the interface FQN followed by the conventional short name.
     *
     * @param array<string, mixed> $options
     *
     * @return list<string>
     */
    public static function serviceCandidates(
        array options,

View on GitHub (pinned to b7419de9cd)

Solutions

Inspect the chained cause: catch the ContainerException and read getPrevious() - the real failure is the inner exception
Reproduce the resolution in isolation: $di->get($name) in a test or tinker session to see the underlying error directly
Fix the factory/constructor: register missing constructor dependencies, guard env/config reads, break circular dependencies with lazy/shared resolution

Example fix

// before
try {
    $guard = $authManager->guard('web');
} catch (\Phalcon\Container\Exceptions\Exception $e) {
    // real cause hidden
}

// after
try {
    $guard = $authManager->guard('web');
} catch (\Phalcon\Container\Exceptions\Exception $e) {
    $cause = $e->getPrevious() ?? $e;
    $log->error('Guard resolution failed: ' . $cause->getMessage());
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    $service = $authResolutionPath; // triggers resolveFresh on Di
} catch (\Phalcon\Container\Exceptions\Exception $e) {
    $cause = $e->getPrevious() ?? $e; // the original DiException carries the real error
    $log->error('DI resolution failed', ['exception' => $cause]);
}

Prevention

Keep DI factory closures small and dependency-only; push I/O and env reads behind their own services
Write a boot smoke test that resolves every auth-related service once and fails on the first throw
Always inspect getPrevious() - the wrapper message alone does not say what broke

When it happens

Trigger: A DI definition whose factory throws (e.g. $di->set('userService', function () { throw new \RuntimeException('db down'); })); resolving a class via the Di class builder whose constructor has unresolvable scalar/typehinted parameters; circular service dependencies.

Common situations: A service factory that connects to a database or reads config at resolve time and fails at runtime; refactored constructors gaining new dependencies that were never registered; container wiring that worked in one environment but not another (missing env var inside a factory).

Related errors

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