yiisoft/yii2 · error · InvalidConfigException

Failed to instantiate component or class "$reference->id".

Error message

Failed to instantiate component or class "$reference->id".

What it means

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().

Source

Thrown at framework/di/Instance.php:156

                return $component;
            }

            throw new InvalidConfigException('Invalid data type: ' . $class . '. ' . $type . ' is expected.');
        } elseif (empty($reference)) {
            throw new InvalidConfigException('The required component is not specified.');
        }

        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.
     */

View on GitHub (pinned to 66f00d18a2)

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).

Example fix

// before
'mailer' => 'app\components\Mailler', // typo

// after
'use app\components\Mailer;'
'mailer' => Mailer::class,

Defensive patterns

Strategy: validation

Validate before calling

$id = $reference instanceof \yii\di\Instance ? $reference->id : $reference;
if (is_string($id) && !Yii::$app->has($id) && !class_exists($id)) {
    throw new \InvalidArgumentException("Component '$id' is neither registered nor an autoloadable class.");
}
$component = \yii\di\Instance::ensure($reference, $type);

Try / catch

use yii\base\InvalidConfigException;

try {
    $component = \yii\di\Instance::ensure('mailer', $type);
} catch (InvalidConfigException $e) {
    $cause = $e->getPrevious(); // the wrapped ReflectionException names the missing class
    Yii::error('Resolution failed: ' . ($cause ? $cause->getMessage() : $e->getMessage()));
    throw;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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