octobercms/october · error · SystemException

Import script is missing definition for 'attributes'

Error message

Import script is missing definition for 'attributes'

What it means

The third required key in a seeds/data.yaml instruction is 'attributes', and it must be a non-empty array (it is force-filled onto the importer). The check throws both when the key is missing/null and when it is present but scalar - so attributes: title fails exactly like omitting it.

Source

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

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

View on GitHub (pinned to b608633a7e)

Solutions

  1. Provide attributes as a YAML sequence of column names: attributes: [title, slug, content].
  2. If the importer truly needs no attributes, check its implementation - this schema requires a non-empty array regardless.
  3. Re-run php artisan theme:seed <theme>.

Example fix

# before - scalar form fails is_array check
- class: 'Acme\Blog\Classes\PostImport'
  file: seeds/posts.yaml
  attributes: title

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

Strategy: validation

Validate before calling

foreach ((array) Yaml::parseFile($themePath . '/seeds/data.yaml') as $i => $ins) {
    if (empty($ins['attributes']) || !is_array($ins['attributes'])) {
        $errors[] = "instruction {$i}: 'attributes' must be a non-empty array";
    }
}

Type guard

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

Try / catch

try {
    \Artisan::call('theme:seed', ['name' => $themeDir]);
} catch (\October\Rain\Exception\SystemException $e) {
    // convert scalar attributes to a YAML sequence, then re-seed
}

Prevention

When it happens

Trigger: A data.yaml entry where attributes is absent, null, a plain string (attributes: title), or an empty list, processed by theme:seed.

Common situations: Authors expecting attributes to be optional; writing a comma string instead of a YAML sequence; indentation errors that turn the sequence into a scalar.

Related errors

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