octobercms/october · error · ApplicationException

The settings page is missing a Model definition.

Error message

The settings page is missing a Model definition.

What it means

Settings controller createModel() instantiates the model for a settings item. Every item registered via a plugin's registerSettings() must declare a 'class' pointing at a settings model (typically one extending System\Models\SettingModel). When the item has no class key or it is an empty string, 'The settings page is missing a Model definition.' is thrown before the form is built.

Source

Thrown at modules/system/controllers/Settings.php:189

    protected function initWidgets($model)
    {
        $config = $model->getFieldConfig();
        $config->model = $model;
        $config->arrayName = class_basename($model);
        $config->context = 'update';

        $widget = $this->makeWidget(\Backend\Widgets\Form::class, $config);
        $widget->bindToController();
        $this->formWidget = $widget;
    }

    /**
     * createModel is an internal method to prepare the form model object
     */
    protected function createModel($item)
    {
        if (!isset($item->class) || !strlen($item->class)) {
            throw new ApplicationException(__('The settings page is missing a Model definition.'));
        }

        $class = $item->class;
        return $class::instance();
    }

    /**
     * findSettingItem locates a setting item for a module or plugin
     */
    protected function findSettingItem($author, $plugin, $code)
    {
        $manager = SettingsManager::instance();

        $moduleOwner = $author;
        $moduleCode = $plugin;
        $item = $manager->findSettingItem($moduleOwner, $moduleCode);

        if (!$item) {

View on GitHub (pinned to b608633a7e)

Solutions

1. Add 'class' => 'Author\Plugin\Models\Settings' to the registerSettings() entry
2. Confirm the class exists, is autoloadable, and extends System\Models\SettingModel (or otherwise provides a singleton instance())
3. Reload the backend settings page after fixing the plugin file

Example fix

// before
'settings' => [
    'label' => 'Shop Settings',
    'icon' => 'icon-cog',
    // no 'class' key
],

// after
'settings' => [
    'label' => 'Shop Settings',
    'icon' => 'icon-cog',
    'class' => 'Acme\Shop\Models\Settings',
],

$item = \System\Classes\SettingsManager::instance()->listItems()[...] ?? null;
if (!$item || empty($item->class)) {
    // do not link to this settings page; it cannot build a model
}

When it happens

Trigger: A registerSettings() entry with no 'class' key; class set to '' ; settings item arrays constructed dynamically where the class element was omitted.

Common situations: Copy-pasted settings registration missing the class line; the model class was renamed and the key left blank; settings items meant as pure menu links mistakenly routed to the settings form.

Related errors

• cms::lang.component.not_found
• The plugin configuration file plugin.yaml should contain the
• Invalid format of the plugin configuration file: %s. The fil
• Unable to find the specified settings.
• Key property ${keyProperty} is not found in the Inspector da

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