yiisoft/yii2 · error · InvalidConfigException

"$reference->id" refers to a get_class($component) component

Error message

"$reference->id" refers to a get_class($component) component. $type is expected.

What it means

After yii\di\Instance::ensure() resolved an Instance reference (an ID like 'cache') through the container, the returned object was not an instance of the expected $type, so it throws '"<id>" refers to a <actual class> component. <type> is expected.' This is the component-ID variant of the type check: the reference resolved fine, but the registered definition points at an incompatible class.

Source

Thrown at framework/di/Instance.php:162

        }

        if (is_string($reference)) {
            $reference = new static($reference);
        } elseif ($type === null || $reference instanceof $type) {
            return $reference;
        }

        if ($reference instanceof self) {
            try {
                $component = $reference->get($container);
            } catch (\ReflectionException $e) {
                throw new InvalidConfigException('Failed to instantiate component or class "' . $reference->id . '".', 0, $e);
            }
            if ($type === null || $component instanceof $type) {
                return $component;
            }

            throw new InvalidConfigException('"' . $reference->id . '" refers to a ' . get_class($component) . " component. $type is expected.");
        }

        $valueType = is_object($reference) ? get_class($reference) : gettype($reference);
        throw new InvalidConfigException("Invalid data type: $valueType. $type is expected.");
    }

    /**
     * Returns the actual object referenced by this Instance object.
     * @param ServiceLocator|Container|null $container the container used to locate the referenced object.
     * If null, the method will first try `Yii::$app` then `Yii::$container`.
     * @return object|null the actual object referenced by this Instance object.
     */
    public function get($container = null)
    {
        try {
            if ($container) {
                return $container->get($this->id);
            }

View on GitHub (pinned to 66f00d18a2)

Solutions

Change the component registration so the ID maps to a class implementing/extending the expected type.
Relax the expectation: pass a parent class/interface that the registered class satisfies, or null to skip checking.
Register the custom object under a new ID and reference that ID where the specific type is needed.
Make the custom class implement the required interface.

Example fix

// before
$cache = Instance::ensure('cache', app\components\CacheInterface::class);
// 'cache' is configured as yii\caching\FileCache

// after
'components' => [
    'cache' => ['class' => app\components\RedisCache::class], // implements CacheInterface
],

Defensive patterns

Strategy: type-guard

Validate before calling

$component = Yii::$app->get('cache'); // resolve the ID first
if (!$component instanceof app\components\CacheInterface) {
    throw new \InvalidArgumentException("'cache' must implement CacheInterface, got " . get_class($component));
}
// now safe to use; equivalent Instance::ensure() call will not throw

Type guard

/** True when the component registered under $id satisfies $type. */
function componentSatisfies(string $id, string $type): bool
{
    if (!Yii::$app->has($id)) {
        return false;
    }
    return Yii::$app->get($id) instanceof $type;
}

Try / catch

try {
    $cache = \yii\di\Instance::ensure('cache', app\components\CacheInterface::class);
} catch (\yii\base\InvalidConfigException $e) {
    // message states which class 'cache' actually is - fix the registration, not the call site
    Yii::error($e->getMessage(), 'config');
    throw;
}

Prevention

When overriding core components, keep the interface contract of the original.
Assert component types once in bootstrap (instanceof on Yii::$app->get(...)) to fail at deploy, not at request time.
Document the required type next to every property documented with Instance::ensure usage.

When it happens

Trigger: Instance::ensure('cache', 'app\components\CacheInterface') when 'cache' is configured as yii\caching\FileCache which does not implement that interface; code declaring Instance::of('user')->get() and passing it where a custom User subclass is required.

Common situations: Overriding a core component ('user', 'db', 'mailer') with a custom class, then passing it to code that requires a stricter type; introducing an interface expectation after the component was already registered with the framework default.

Related errors

AI-assisted analysis of yiisoft/yii2@66f00d18a2 (2026-08-17). Data as JSON: /api/errors/eb88103110356956. Report an issue: GitHub.