octobercms/october · error · SystemException

Import file '{$fileName}' does not exist.

Error message

Import file '{$fileName}' does not exist.

What it means

The 'file' value in a seeds/data.yaml instruction is resolved as themePath . '/' . $fileName. If that path does not exist on disk, seeding aborts with the relative filename in the message. This catches wrong extensions, wrong subpaths, and data files that were never shipped with the theme.

Source

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

        $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')) {
            $importModel->setSourcePrefix($this->themePath);
        }

        $importModel->importFile($importFile, ['matches' => $matches, 'sessionKey' => str_random(40)]);

        $stats = $importModel->getResultStats();
        $this->note("- <info>{$importName}</info>: {$stats->created} Created / {$stats->updated} Updated / {$stats->skippedCount} Skipped");
    }
}

View on GitHub (pinned to b608633a7e)

Solutions

  1. Check the exact path: ls themes/<dir>/<file-from-yaml> and align the YAML value with what is on disk (extension, case, subfolder).
  2. Ensure the data file is actually shipped - not excluded by .gitignore or packaging rules.
  3. Re-run php artisan theme:seed <theme> once the file exists.

Example fix

# before - wrong extension
  file: seeds/posts.yml

# after - matches the file on disk (themes/demo/seeds/posts.yaml)
  file: seeds/posts.yaml
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
    \Artisan::call('theme:seed', ['name' => $themeDir]);
} catch (\October\Rain\Exception\SystemException $e) {
    // align the 'file' path with the real file under themes/<dir>/, then re-seed
}

Prevention

When it happens

Trigger: theme:seed with file: seeds/posts.yml when the file on disk is seeds/posts.yaml; file: content/about.htm when the file lives in the theme's content/ folder but was not deployed; case mismatch in the path on a case-sensitive filesystem.

Common situations: Seed files edited on macOS/Windows where case and extension slips go unnoticed, then failing on Linux; themes packaged without the seed data files; paths written assuming the theme root when the file sits elsewhere.

Related errors

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