yiisoft/yii2 · error · InvalidConfigException

The required component is not specified.

Error message

The required component is not specified.

What it means

yii\di\Instance::ensure() received an empty value (empty array, empty string, null, false, 0) where a component reference is required, and throws 'The required component is not specified.' The method accepts a component ID string, a config array, an Instance, or a ready object - none of which can be empty, so there is nothing to resolve.

Source

Thrown at framework/di/Instance.php:143

                $container = Yii::$container;
            }
            if (isset($reference['__class'])) {
                $class = $reference['__class'];
                unset($reference['__class'], $reference['class']);
            } elseif (isset($reference['class'])) {
                $class = $reference['class'];
                unset($reference['class']);
            } else {
                $class = $type;
            }
            $component = $container->get($class, [], $reference);
            if ($type === null || $component instanceof $type) {
                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;
            }

View on GitHub (pinned to 66f00d18a2)

Solutions

  1. Provide a real reference: a component ID string, a config array with a 'class' key, or an object instance.
  2. Default missing env values: $id = getenv('CACHE_ID') ?: 'cache'; before passing it on.
  3. Skip setting the property entirely when the component is not configured, instead of setting it to an empty value.
  4. Audit config merges so later files can't overwrite a valid component config with [].

Example fix

// before
'cache' => [], // or 'cache' => '' / null from an unset env var

// after
'cache' => ['class' => yii\caching\FileCache::class],
// or when env-driven
'cache' => getenv('CACHE_CLASS') ?: yii\caching\FileCache::class,
Defensive patterns

Strategy: validation

Validate before calling

if (empty($reference)) {
    throw new \InvalidArgumentException('Component reference must be an ID, config array, or object; got empty value.');
}
$component = \yii\di\Instance::ensure($reference, $type);

Type guard

/** True when the value is a usable component reference (non-empty ID/config/Instance/object). */
function isNonEmptyReference($value): bool
{
    if (is_string($value)) {
        return $value !== '';
    }
    if (is_array($value)) {
        return $value !== [];
    }
    return $value instanceof \yii\di\Instance || is_object($value);
}

Try / catch

try {
    $component = \yii\di\Instance::ensure($value, $type);
} catch (\yii\base\InvalidConfigException $e) {
    if (strpos($e->getMessage(), 'The required component is not specified') === 0) {
        // fall back to a sane default component instead of failing
        $component = \yii\di\Instance::ensure('cache', $type);
    } else {
        throw $e;
    }
}

Prevention

When it happens

Trigger: A typed component property is set to [] or '' in config; a value sourced from an environment variable that is unset (null/false) is passed through; Instance::ensure(getenv('CACHE_ID'), Cache::class) when the variable is not defined.

Common situations: Env-driven configuration where a variable is missing in one environment (staging/CI); optional components represented as empty arrays in defaults merged with Yi\config or array_merge; YAML/JSON config round-trips turning null into ''.

Related errors

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