octobercms/october · error · SystemException

The addFormField method should be called when defining field

Error message

The addFormField method should be called when defining fields inside a model. Try using addField, addTabField or addSecondaryTabField instead.

What it means

Error "The addFormField method should be called when defining fields inside a model. Try using addField, addTabField or addSecondaryTabField instead." thrown in octobercms/october.

Source

Thrown at modules/backend/widgets/form/IsFormElement.php:29

 *
 * @see \October\Contracts\Element\FormElement
 * @package october\backend
 * @author Alexey Bobkov, Samuel Georges
 */
trait IsFormElement
{
    /**
     * @var FieldsetDefinition|null activeTabSection where fields are currently being added
     */
    protected $activeTabSection = null;

    /**
     * addFormField adds a field to the fieldset
     */
    public function addFormField(string $fieldName, ?string $label = null): FieldDefinition
    {
        if ($this->activeTabSection === null) {
            throw new SystemException("The addFormField method should be called when defining fields inside a model. Try using addField, addTabField or addSecondaryTabField instead.");
        }

        $fieldObj = new FormField([
            'fieldName' => $fieldName,
            'label' => $label,
            'arrayName' => $this->arrayName,
            'idPrefix' => $this->getId()
        ]);

        $this->allFields[$fieldName] = $fieldObj;

        $this->activeTabSection->addField($fieldName, $fieldObj);

        return $fieldObj;
    }

    /**
     * getFormFieldset returns the current fieldset definition

View on GitHub (pinned to b608633a7e)

When it happens

Trigger: Thrown at modules/backend/widgets/form/IsFormElement.php:29 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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