octobercms/october · error · SystemException

The provided model class ":modelClass" for the recordfinder

Error message

The provided model class ":modelClass" for the recordfinder is invalid

What it means

Thrown by Tailor's RecordFinder content field when the configured modelClass does not exist as a loadable PHP class. Before rendering the record finder relation, getRelatedModel() calls class_exists($this->modelClass) and aborts with a SystemException if the class cannot be autoloaded. This is a configuration error in the blueprint YAML for a recordfinder field.

Source

Thrown at modules/tailor/contentfields/RecordFinderField.php:325

        $toTransfer = ['label', 'list', 'form', 'view', 'manage'];
        foreach ($toTransfer as $transfer) {
            if (isset($this->controller[$transfer])) {
                $fieldConfig[$transfer] = is_array($this->controller[$transfer])
                    ? array_merge($fieldConfig[$transfer], (array) $this->controller[$transfer])
                    : $this->controller[$transfer];
            }
        }

        $field->controller($fieldConfig);
    }

    /**
     * getRelatedModel returns the related model to use
     */
    protected function getRelatedModel()
    {
        if (!class_exists($this->modelClass)) {
            throw new SystemException(Lang::get('backend::lang.recordfinder.invalid_model_class', ['modelClass' => $this->modelClass]));
        }

        return new $this->modelClass;
    }
}

View on GitHub (pinned to b608633a7e)

Solutions

1. Check the modelClass value in your blueprint YAML (fields.<name>.modelClass) and correct the spelling to the exact fully qualified class name, e.g. modelClass: \RainLab\Blog\Models\Post
2. Verify the class exists and is autoloadable: run php artisan tinker and check class_exists('\\Vendor\\Plugin\\Models\\Name')
3. Confirm the plugin providing the model is installed and enabled (php artisan plugin:list); install or enable it if missing
4. If you renamed the model class, update every blueprint that references the old name and clear cached blueprint data (php artisan cache:clear, php artisan tailor:sync)

Example fix

# before (blueprint.yaml)
fields:
  posts:
    type: recordfinder
    modelClass: RainLab\Blog\Models\Postes   # typo

# after
fields:
  posts:
    type: recordfinder
    modelClass: \RainLab\Blog\Models\Post

// Before shipping a blueprint, verify the model class resolves
use Illuminate\Support\Arr;

$modelClass = Arr::get($fieldConfig, 'modelClass');
if (!class_exists($modelClass)) {
    throw new InvalidArgumentException("recordfinder modelClass [{$modelClass}] does not exist");
}

function isValidRecordFinderModel(?string $modelClass): bool
{
    return $modelClass !== null && class_exists($modelClass)
        && is_subclass_of($modelClass, \October\Rain\Database\Model::class);
}

When it happens

Trigger: Defining a recordfinder content field in a Tailor blueprint whose modelClass value is misspelled, not fully qualified (e.g. Author instead of \RainLab\Blog\Models\Post), or points to a class in a plugin that is not installed/registered. Also triggered when the record finder relation is used (getRelatedModel is called during relation definition) and the string is empty or names a non-model class.

Common situations: Typo in the YAML handle; forgetting the leading backslash or full namespace of the target model; referencing a plugin model after disabling or uninstalling the plugin; renaming a model class without updating blueprints; case-sensitivity differences on Linux (e.g. Post vs post) after developing on Windows/macOS.

Related errors

• Repeater must specify either a "form" or "group" property fo
• Missing relation definition for inverse field '{$this->inver
• Section handle [{$handle}] not found
• Global handle [{$handle}] not found
• Could not spawn from path [{$spawnPath}]

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