What causes "Invalid field name: {$fieldName}." in octobercms/october?

Rename the field using only letters, numbers and underscores, e.g. `my_field:`.

octobercms/october · error · BlueprintException

Invalid field name: {$fieldName}.

Error message

Invalid field name: {$fieldName}.

What it means

The verifier iterates every field returned by the compiled fieldset (including fields pulled in via `import:` from shared fieldsets) and requires each field name to match /^[a-zA-Z0-9_]+$/. Any other character — dash, dot, space, unicode — makes the name unusable as a content column and model attribute, so validation fails naming the field.

Source

Thrown at modules/tailor/classes/BlueprintVerifier.php:233

        $fields = $blueprint->fields ?? [];

        if ($blueprint instanceof EntryBlueprint && is_array($blueprint->groups)) {
            foreach ($blueprint->groups as $group) {
                $fields += $group['fields'] ?? [];
            }
        }

        // Validate source references from raw config (before fieldset expansion)
        $this->validateSourceReferences($blueprint, $fields);

        $fieldset = FieldManager::instance()->makeFieldset(['fields' => $fields]);
        $fieldset->validate();

        // Check invalid and reserved field names
        foreach ($fieldset->getAllFields() as $fieldName => $fieldObj) {
            if (!preg_match('/^[a-zA-Z0-9\_]+$/', $fieldName)) {
                $lineNo = $this->findLineFromKeyValPair($blueprint->content, $fieldName, '');
                throw new BlueprintException($blueprint, "Invalid field name: {$fieldName}.", $lineNo);
            }

            if (in_array($fieldName, $this->reservedFieldNames)) {
                $lineNo = $this->findLineFromKeyValPair($blueprint->content, $fieldName, '');
                throw new BlueprintException($blueprint, "Field name is reserved: {$fieldName}.", $lineNo);
            }
        }
    }

    /**
     * validateSourceReferences validates source references in raw field config recursively
     */
    protected function validateSourceReferences(Blueprint $blueprint, array $fields)
    {
        foreach ($fields as $fieldName => $fieldConfig) {
            if (!is_array($fieldConfig)) {
                continue;
            }

View on GitHub (pinned to b608633a7e)

Solutions

Rename the field using only letters, numbers and underscores, e.g. `my_field:`.
If the error names a field you don't recognise in the blueprint, grep your theme's fieldset files (`fields/*.yaml`) — it was merged in via `import:`.
Check for invisible characters or trailing spaces around the YAML key; re-quote the key if needed.

Example fix

# before
fields:
  my-field:
    label: My Field
    type: text

# after
fields:
  my_field:
    label: My Field
    type: text

Defensive patterns

Strategy: validation

Validate before calling

foreach ($fields as $name => $config) {
    if (!preg_match('/^[a-zA-Z0-9_]+$/', (string) $name)) {
        throw new InvalidArgumentException("Invalid field name: {$name}");
    }
}

Type guard

function isValidTailorFieldName(string $name): bool
{
    return (bool) preg_match('/^[a-zA-Z0-9_]+$/', $name);
}

Try / catch

try {
    // blueprint scan / tailor:refresh
} catch (\Tailor\Classes\BlueprintException $e) {
    // message contains the offending field name; grep blueprints AND imported fieldsets
}

Prevention

Standardize on snake_case field names in all blueprint and fieldset YAML.
Lint field keys in CI with the same regex Tailor uses: /^[a-zA-Z0-9_]+$
When importing shared fieldsets, lint the imported files too — the verifier checks the expanded field list.

When it happens

Trigger: A blueprint or imported fieldset defines `my-field:`, `foo.bar:`, `items []:` or a quoted key containing a space. Because getAllFields() returns the expanded fieldset, the offending key may live in an imported fields/*.yaml file rather than the blueprint itself.

Common situations: Field names copy-pasted from HTML form markup (kebab-case); YAML keys with trailing spaces or tabs; non-ASCII/localised field names; a key accidentally parsed as a nested map (e.g. `foo: { }` style).

Related errors

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