{"record":{"id":"cdffa7b75ea19f54","repo":"yiisoft/yii2","slug":"failed-to-instantiate-component-or-class-referen","errorCode":null,"errorMessage":"Failed to instantiate component or class \"$reference->id\".","messagePattern":"Failed to instantiate component or class \"\\$reference->id\"\\.","errorType":"exception","errorClass":"InvalidConfigException","httpStatus":null,"severity":"error","filePath":"framework/di/Instance.php","lineNumber":156,"sourceCode":"                return $component;\n            }\n\n            throw new InvalidConfigException('Invalid data type: ' . $class . '. ' . $type . ' is expected.');\n        } elseif (empty($reference)) {\n            throw new InvalidConfigException('The required component is not specified.');\n        }\n\n        if (is_string($reference)) {\n            $reference = new static($reference);\n        } elseif ($type === null || $reference instanceof $type) {\n            return $reference;\n        }\n\n        if ($reference instanceof self) {\n            try {\n                $component = $reference->get($container);\n            } catch (\\ReflectionException $e) {\n                throw new InvalidConfigException('Failed to instantiate component or class \"' . $reference->id . '\".', 0, $e);\n            }\n            if ($type === null || $component instanceof $type) {\n                return $component;\n            }\n\n            throw new InvalidConfigException('\"' . $reference->id . '\" refers to a ' . get_class($component) . \" component. $type is expected.\");\n        }\n\n        $valueType = is_object($reference) ? get_class($reference) : gettype($reference);\n        throw new InvalidConfigException(\"Invalid data type: $valueType. $type is expected.\");\n    }\n\n    /**\n     * Returns the actual object referenced by this Instance object.\n     * @param ServiceLocator|Container|null $container the container used to locate the referenced object.\n     * If null, the method will first try `Yii::$app` then `Yii::$container`.\n     * @return object|null the actual object referenced by this Instance object.\n     */","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/yiisoft/yii2/blob/66f00d18a29b520f85e8e8f1e32d1e7e7b556cac/framework/di/Instance.php#L138-L174","documentation":"yii\\di\\Instance::ensure() held an Instance whose ->get($container) call raised a ReflectionException - typically because the referenced class does not exist or cannot be autoloaded - and wraps it as InvalidConfigException 'Failed to instantiate component or class \"<id>\".' The original ReflectionException is chained as the previous exception, so the root cause (usually 'Class X does not exist') is preserved in getCause()/getPrevious().","triggerScenarios":"Instance::ensure('mailer', MailerInterface::class) where the container resolves 'mailer' to a class name string with a typo; a config entry like 'user' => 'app\\models\\User' pointing at a misspelled/renamed class; a component ID that is neither registered nor a loadable class, so the container falls back to reflecting it as a class name.","commonSituations":"Class renamed or moved during refactoring while old string references remain in config; missing composer package (yii2-swiftmailer, yii2-redis) so the configured class is not autoloadable; typo in a namespaced class string; case-sensitivity differences between Windows dev and Linux prod.","solutions":["Check the chained exception (getPrevious()) to see the exact ReflectionException message naming the class.","Fix the class reference: correct the namespace/typo, or import the package that provides it (composer require ...).","If the value is a component ID, register that ID in the container/app config instead of relying on class fallback.","Run composer dump-autoload and verify the class exists with class_exists($class)."],"exampleFix":"// before\n'mailer' => 'app\\components\\Mailler', // typo\n\n// after\n'use app\\components\\Mailer;'\n'mailer' => Mailer::class,","handlingStrategy":"validation","validationCode":"$id = $reference instanceof \\yii\\di\\Instance ? $reference->id : $reference;\nif (is_string($id) && !Yii::$app->has($id) && !class_exists($id)) {\n    throw new \\InvalidArgumentException(\"Component '$id' is neither registered nor an autoloadable class.\");\n}\n$component = \\yii\\di\\Instance::ensure($reference, $type);","typeGuard":null,"tryCatchPattern":"use yii\\base\\InvalidConfigException;\n\ntry {\n    $component = \\yii\\di\\Instance::ensure('mailer', $type);\n} catch (InvalidConfigException $e) {\n    $cause = $e->getPrevious(); // the wrapped ReflectionException names the missing class\n    Yii::error('Resolution failed: ' . ($cause ? $cause->getMessage() : $e->getMessage()));\n    throw;\n}","preventionTips":["Run composer dump-autoload after adding/renameing classes referenced as strings in config.","Prefer SomeClass::class constants over hand-typed strings in configuration.","Add a boot check that class_exists() every class referenced in the components config.","Verify required extensions/packages (yii2-swiftmailer, yii2-redis...) are installed in every environment."],"tags":["yii2","dependency-injection","instance","class-not-found","config"],"backgroundTag":"class-not-found","analyzedSha":"66f00d18a29b520f85e8e8f1e32d1e7e7b556cac","analyzedAt":"2026-08-17T05:17:23.470Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}