octobercms/october · error · CmsException

cms::lang.component.not_found

Error message

cms::lang.component.not_found

What it means

When a component declared on a page or layout cannot be created (ComponentManager::makeComponent returns null because the component is unregistered, its plugin is missing or disabled), the controller either sets the variable to null silently (default) or, with cms.strict_components enabled in config/cms.php, throws this CmsException naming the component.

Source

Thrown at modules/cms/classes/controller/HasComponentHelpers.php:59

     * @param array  $properties
     * @param bool   $addToLayout
     * @return ComponentBase|null
     */
    public function addComponent($name, $alias, $properties = [], $addToLayout = false)
    {
        $manager = ComponentManager::instance();

        if ($addToLayout) {
            $componentObj = $manager->makeComponent($name, $this->layoutObj, $properties);
        }
        else {
            $componentObj = $manager->makeComponent($name, $this->pageObj, $properties);
        }

        if (!$componentObj) {
            $strictMode = Config::get('cms.strict_components', false);
            if ($strictMode) {
                throw new CmsException(Lang::get('cms::lang.component.not_found', ['name' => $name]));
            }
            else {
                return $this->vars[$alias] = null;
            }
        }

        $componentObj->alias = $alias;

        if ($addToLayout) {
            $this->layout->components[$alias] = $componentObj;
        }
        else {
            $this->page->components[$alias] = $componentObj;
        }

        $this->vars[$alias] = $componentObj->makePrimaryAccessor();

        $this->parseRouteParamsOnComponent($componentObj, $this->router->getParameters());

View on GitHub (pinned to b608633a7e)

Solutions

1. Register the component in the plugin's registerComponents() and confirm the plugin is installed and enabled
2. Fix the reference: correct plugin namespace and component name, correct casing
3. Remove the stale component entry from the page/layout
4. If you must render anyway, set 'strict_components' => false in config/cms.php to restore lenient behaviour

Example fix

// before: page references a component from a disabled plugin
[myPlugin someWidget]
==

// after: remove the stale reference (or reinstall/re-enable the plugin first)
==

use \Cms\Classes\ComponentManager;
$manager = ComponentManager::instance();
foreach ($declaredComponentNames as $name) {
    if (!$manager->hasComponent($name)) {
        // skip, log, or fail before the page renders
    }
}

try { $this->addComponent('X', 'alias', $props); } catch (\Cms\Classes\CmsException $e) { // strict mode: component unresolved, degrade gracefully }

When it happens

Trigger: A page or layout 'components' declaration (or addComponent() call) referencing a component ComponentManager cannot resolve, e.g. 'MyPlugin::Items' from an uninstalled plugin, while 'cms.strict_components' => true.

Common situations: Plugin disabled or uninstalled while pages still reference its components; typo in the component name or plugin prefix; enabling strict_components (newer Winter enables it in dev) exposing previously silent breakage; environments drifting between strict and lenient configs.

Related errors

• Component not found
• cms::lang.theme.edit.not_set
• cms::lang.component.no_records
• cms::lang.component.not_found
• Component does use a default partial

AI-assisted analysis of octobercms/october@b608633a7e (2026-08-21). Data as JSON: /api/errors/eb9309c4df4cfa4d. Report an issue: GitHub.