octobercms/october · error · SystemException

NestedItems must specify either a "form" property for the fo

Error message

NestedItems must specify either a "form" property for the form fields

What it means

NestedItemsField (repeatable nested item sets) builds its fieldset solely from the `form:` key of the field config, exactly like nestedform. validateConfig() throws when fieldsetConfig is null, i.e. the field was declared without a usable `form:` block.

Source

Thrown at modules/tailor/contentfields/NestedItemsField.php:40

    public $fieldsetConfig;

    /**
     * defineConfig will process the field configuration.
     */
    public function defineConfig(array $config)
    {
        if (isset($config['form'])) {
            $this->fieldsetConfig = (array) $config['form'];
        }
    }

    /**
     * validateConfig
     */
    public function validateConfig()
    {
        if ($this->fieldsetConfig === null) {
            throw new SystemException('NestedItems must specify either a "form" property for the form fields');
        }
    }

    /**
     * defineFormField will define how a field is displayed in a form.
     */
    public function defineFormField(FormElement $form, $context = null)
    {
        $fieldConfig = [
            'label' => $this->label,
            'list' => [],
            'form' => [],
            'customMessages' => (array) $this->customMessages,
            'popupSize' => $this->popupSize,
            'view' => [
                'showSorting' => false,
                'toolbarButtons' => 'create|delete',
                'recordsPerPage' => $this->recordsPerPage,

View on GitHub (pinned to b608633a7e)

Solutions

Add a `form:` block with a `fields:` map under the nesteditems field.
If you used `fields:` instead of `form:`, rename the key — nesteditems expects `form:`.
Verify YAML indentation so `form:` parses as part of the field config.

Example fix

# before
fields:
  specs:
    label: Specs
    type: nesteditems
    fields:
      name: { type: text }

# after
fields:
  specs:
    label: Specs
    type: nesteditems
    form:
      fields:
        name: { type: text }

Defensive patterns

Strategy: validation

Validate before calling

$fieldConfig = $blueprintContent['fields'][$fieldName] ?? [];
if (($fieldConfig['type'] ?? '') === 'nesteditems' && !isset($fieldConfig['form'])) {
    throw new InvalidArgumentException("nesteditems field '{$fieldName}' requires a form: block (not fields:).");
}

Type guard

function hasNestedItemsForm(array $fieldConfig): bool
{
    return isset($fieldConfig['form']) && is_array($fieldConfig['form']);
}

Try / catch

try {
    // blueprint validation / tailor:refresh
} catch (\SystemException $e) {
    // nesteditems needs form:, not fields: — rename the key and revalidate
}

Prevention

Remember nesteditems/nestedform take `form:`, unlike top-level blueprint sections which take `fields:`.
Lint blueprint YAML in CI for field types requiring form blocks.

When it happens

Trigger: A field `{type: nesteditems}` is defined with no `form:` key, or the key exists but is empty/indentation-broken so the constructor never assigns fieldsetConfig. The error surfaces when Tailor validates or compiles the blueprint.

Common situations: Copy-pasting a nesteditems example that omits form; intending to configure items via `fields:` (unsupported — nesteditems uses `form:`); indentation errors after refactoring YAML.

Related errors

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