octobercms/october · error · SystemException

Import script is missing definition for 'class'

Error message

Import script is missing definition for 'class'

What it means

Each entry in a theme's seeds/data.yaml must define class (the importer class to instantiate), file (the data file), and attributes. processSeedInstruction() throws this SystemException when the 'class' key is absent or null, before anything is executed - a seed-instruction schema check.

Source

Thrown at modules/cms/models/ThemeSeed.php:214

        foreach ($instructions as $instruction) {
            $this->processSeedInstruction($instruction);
        }
    }

    /**
     * processSeedInstruction
     */
    protected function processSeedInstruction($instruction)
    {
        $importName = $instruction['name'] ?? 'Import Data';
        $className = $instruction['class'] ?? null;
        $fileName = $instruction['file'] ?? null;
        $attributes = $instruction['attributes'] ?? null;
        $matches = $instruction['matches'] ?? null;

        if (!$className) {
            throw new SystemException("Import script is missing definition for 'class'");
        }
        if (!$fileName) {
            throw new SystemException("Import script is missing definition for 'file'");
        }
        if (!$attributes || !is_array($attributes)) {
            throw new SystemException("Import script is missing definition for 'attributes'");
        }

        if (!class_exists($className)) {
            throw new SystemException("Import class '{$className}' does not exist.");
        }

        $importFile = $this->themePath . '/' . $fileName;
        if (!File::exists($importFile)) {
            throw new SystemException("Import file '{$fileName}' does not exist.");
        }

        $importModel = new $className;

View on GitHub (pinned to b608633a7e)

Solutions

  1. Add a fully-qualified 'class' value to the failing instruction in seeds/data.yaml (it must be an importer that supports importFile).
  2. Confirm the class resolves before re-seeding: class_exists('Acme\Blog\Classes\PostImport').
  3. Re-run php artisan theme:seed <theme>.

Example fix

# before (themes/demo/seeds/data.yaml)
- name: Blog posts
  file: seeds/posts.yaml
  attributes: [title, content]

# after
- name: Blog posts
  class: 'Acme\Blog\Classes\PostImport'
  file: seeds/posts.yaml
  attributes: [title, content]
Defensive patterns

Strategy: validation

Validate before calling

use Symfony\Component\Yaml\Yaml;
use File;

function seedInstructionsValid(string $themePath): array
{
    $errors = [];
    $file = $themePath . '/seeds/data.yaml';
    if (!File::isFile($file)) return $errors;
    foreach ((array) Yaml::parseFile($file) as $i => $ins) {
        if (empty($ins['class'])) $errors[] = "instruction {$i}: missing 'class'";
    }
    return $errors;
}

Type guard

function isCompleteSeedInstruction(array $i): bool
{
    return isset($i['class']) && $i['class'] !== '';
}

Try / catch

try {
    \Artisan::call('theme:seed', ['name' => $themeDir]);
} catch (\October\Rain\Exception\SystemException $e) {
    // message names the missing key; fix that entry in seeds/data.yaml
}

Prevention

When it happens

Trigger: A data.yaml instruction like { name: Pages, file: seeds/pages.yaml, attributes: [title] } with no class key, or class: with an empty value, run through theme:seed or activation seeding.

Common situations: Hand-written seed files copied from examples that omitted the class; renaming the key (className instead of class); YAML indentation putting class under a sibling key.

Related errors

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