{"record":{"id":"2cb900a952fe6ef9","repo":"phalcon/cphalcon","slug":"instance-name-not-found","errorCode":null,"errorMessage":"Instance '{name}' not found","messagePattern":"Instance '(.+?)' not found","errorType":"exception","errorClass":"Phalcon\\Container\\Exceptions\\InstanceNotFound","httpStatus":null,"severity":"error","filePath":"phalcon/Container/Container.zep","lineNumber":269,"sourceCode":"        if (!array_key_exists(name, this->services)) {\n            throw new ServiceNotFound(name);\n        }\n\n        return this->services[name];\n    }\n\n    /**\n     * Return a stored instance\n     *\n     * @param string $name\n     *\n     * @return object\n     * @throws InstanceNotFound\n     */\n    public function getInstance(string name) -> object\n    {\n        if (!array_key_exists(name, this->instances)) {\n            throw new InstanceNotFound(name);\n        }\n\n        return this->instances[name];\n    }\n\n    /**\n     * Return a parameter\n     *\n     * @param string $name\n     *\n     * @return mixed\n     * @throws ParameterNotFound\n     */\n    public function getParameter(string name) -> mixed\n    {\n        if (!array_key_exists(name, this->parameters)) {\n            throw new ParameterNotFound(name);\n        }","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Container/Container.zep#L251-L287","documentation":"getInstance() returns only shared instances the container has already built and cached during a resolving get(). It throws InstanceNotFound when no built instance exists under that name yet — merely registering a definition is not enough, and definitions resolved through $new() (cache=false) are never stored.","triggerScenarios":"Calling getInstance('db') before any get('db') has run; resolving via $container->$new('db') and then reading getInstance('db'); the definition using a factory lifetime that skips caching.","commonSituations":"Boot-order bugs where code reads a shared instance before first use; habits carried over from Phalcon\\Di's getShared(); mixing fresh-resolution and cached-instance access patterns; tests that assume the container pre-populates instances.","solutions":["Resolve once first: $db = $container->get('db'); after that getInstance('db') returns the cached instance","Guard with $container->hasInstance('db') before calling","If you just need the object, use get('db') — it builds and caches when the definition lifetime allows","Check the definition lifetime — non-cached (factory) lifetimes may never populate the instance store"],"exampleFix":"// before\n$db = $container->getInstance('db'); // InstanceNotFound\n\n// after\n$db = $container->hasInstance('db')\n    ? $container->getInstance('db')\n    : $container->get('db');","handlingStrategy":"validation","validationCode":"$db = $container->hasInstance('db')\n    ? $container->getInstance('db')\n    : $container->get('db'); // builds and caches","typeGuard":null,"tryCatchPattern":"use Phalcon\\Container\\Exceptions\\InstanceNotFound;\n\ntry {\n    $db = $container->getInstance('db');\n} catch (InstanceNotFound $e) {\n    $db = $container->get('db');\n}","preventionTips":["Use get() as the normal access path; reserve getInstance() for code that must observe the cached instance","Remember $new() (fresh resolution) never populates the instance store","In tests, resolve shared services once in setUp() before asserting on instances"],"tags":["di-container","shared-instance","instance-not-found","phalcon"],"backgroundTag":"service-not-found","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}