octobercms/october · error · SystemException

Import script is missing definition for 'file'

Error message

Import script is missing definition for 'file'

What it means

Same seed-instruction schema check as the missing-class error, but for the 'file' key: processSeedInstruction() requires every data.yaml instruction to name the data file (resolved relative to the theme directory) that the importer will read. A missing or null file key aborts seeding before any class is loaded.

Source

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

        }
    }

    /**
     * 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;
        $importModel->forceFill($attributes);

        if (method_exists($importModel, 'setSourcePrefix')) {

View on GitHub (pinned to b608633a7e)

Solutions

  1. Add the 'file' key pointing at the data file relative to the theme root, e.g. file: seeds/posts.yaml.
  2. Verify the path exists on disk: File::exists($themePath.'/seeds/posts.yaml').
  3. Re-run php artisan theme:seed <theme>.

Example fix

# before
- name: Blog posts
  class: 'Acme\Blog\Classes\PostImport'
  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

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

Type guard

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

Try / catch

try {
    \Artisan::call('theme:seed', ['name' => $themeDir]);
} catch (\October\Rain\Exception\SystemException $e) {
    // add the 'file' key to the flagged instruction, then re-seed
}

Prevention

When it happens

Trigger: A data.yaml entry with class and attributes but no file key (or file: left empty), processed by theme:seed; typically after trimming an example down or a copy-paste that dropped the line.

Common situations: Seed files authored from scratch following older docs; key spelled files instead of file; empty value from a YAML templating step.

Related errors

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