{"record":{"id":"c776eee8816276e7","repo":"phalcon/cphalcon","slug":"failed-to-resolve-name-from-the-di-container","errorCode":null,"errorMessage":"Failed to resolve '{name}' from the Di container","messagePattern":"Failed to resolve '(.+?)' from the Di container","errorType":"exception","errorClass":"Phalcon\\Container\\Exceptions\\Exception","httpStatus":null,"severity":"error","filePath":"phalcon/Auth/Internal/ContainerResolver.zep","lineNumber":136,"sourceCode":"                    \"Cannot resolve a fresh '\" . name\n                    . \"': it is not bound in the container\"\n                );\n            }\n\n            return container->{\"new\"}(name);\n        }\n\n        if (true !== container->has(name) && !class_exists(name)) {\n            throw new ContainerException(\n                \"Cannot resolve a fresh '\" . name\n                . \"': it is not registered in the Di and is not an existing class\"\n            );\n        }\n\n        try {\n            return container->get(name);\n        } catch DiException, e {\n            throw new ContainerException(\n                \"Failed to resolve '\" . name . \"' from the Di container\",\n                0,\n                e\n            );\n        }\n    }\n\n    /**\n     * Builds the ordered candidate list for a framework service:\n     * an explicit override from options['services'][key] if present,\n     * otherwise the interface FQN followed by the conventional short name.\n     *\n     * @param array<string, mixed> $options\n     *\n     * @return list<string>\n     */\n    public static function serviceCandidates(\n        array options,","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Auth/Internal/ContainerResolver.zep#L118-L154","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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"],"exampleFix":"// before\ntry {\n    $guard = $authManager->guard('web');\n} catch (\\Phalcon\\Container\\Exceptions\\Exception $e) {\n    // real cause hidden\n}\n\n// after\ntry {\n    $guard = $authManager->guard('web');\n} catch (\\Phalcon\\Container\\Exceptions\\Exception $e) {\n    $cause = $e->getPrevious() ?? $e;\n    $log->error('Guard resolution failed: ' . $cause->getMessage());\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    $service = $authResolutionPath; // triggers resolveFresh on Di\n} catch (\\Phalcon\\Container\\Exceptions\\Exception $e) {\n    $cause = $e->getPrevious() ?? $e; // the original DiException carries the real error\n    $log->error('DI resolution failed', ['exception' => $cause]);\n}","preventionTips":["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"],"tags":["auth","dependency-injection","exception-chaining","factory-error"],"backgroundTag":"service-resolution-failed","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}