octobercms/october · warning · ValidationException

Invalid drop-down option key: :key. Option keys can contain

Error message

Invalid drop-down option key: :key. Option keys can contain only digits, Latin letters and characters _ and -

What it means

ValidationException thrown while parsing pipe-separated dropdown options for a snippet property ('key:Label|key2:Label2'). When an option declares a key, that key must match /^[0-9a-z-_]+$/i — digits, Latin letters, underscore and hyphen only. Spaces, dots, colons-in-key, or unicode characters in the key are rejected when the snippet is saved.

Source

Thrown at modules/cms/classes/Snippet.php:299

                    )]);
                }

                return $result;
            }
        }

        $options = explode('|', $optionsString);

        $result = [];
        foreach ($options as $index => $optionStr) {
            $parts = explode(':', $optionStr, 2);

            if (count($parts) > 1) {
                $key = trim($parts[0]);

                if (strlen($key)) {
                    if (!preg_match('/^[0-9a-z-_]+$/i', $key)) {
                        throw new ValidationException(['snippetProperties' => __("Invalid drop-down option key: :key. Option keys can contain only digits, Latin letters and characters _ and -", ['key'=>$key])]);
                    }

                    $result[$key] = trim($parts[1]);
                }
                else {
                    $result[$index] = trim($optionStr);
                }
            }
            else {
                $result[$index] = trim($optionStr);
            }
        }

        return $result;
    }

    /**
     * dropDownOptionsToString is a helper to convert the an array to a string

View on GitHub (pinned to b608633a7e)

Solutions

Rewrite keys using only [A-Za-z0-9_-]: 'option-one:First|my-key:Second'.
Keep human text on the label side of the colon (after it), never in the key.
Lint your snippet property definitions with the same regex before shipping.

Example fix

// before — space and dot are illegal in keys
'options' => 'Option One:First|my.key:Second'

// after — keys use digits, letters, _ and - only
'options' => 'option-one:First|my-key:Second'

Defensive patterns

Strategy: validation

Validate before calling

$key = trim(explode(':', $optionStr, 2)[0]);
if (!preg_match('/^[0-9a-z-_]+$/i', $key)) {
    // sanitize before saving the snippet definition
    $key = strtolower(preg_replace('/[^0-9a-zA-Z-_]+/', '-', $key));
}

Try / catch

try {
    $options = Snippet::dropDownOptionsToArray($optionsString);
} catch (Winter\Storm\Exception\ValidationException $e) {
    // editor shows the offending :key — fix the definition, no runtime retry
    return back()->withErrors($e->getErrors());
}

Prevention

Keep option keys machine-safe: lowercase, hyphens/underscores, no spaces.
Put all human-readable text in the label (after the colon).
Lint snippet/component YAML through the key regex in CI.

When it happens

Trigger: Defining `'options' => 'Option One:First|my.key:Second'` on a component/snippet property; authoring snippet property YAML with human-readable labels used as keys; pasting option lists from spreadsheets.

Common situations: Theme/plugin authors writing natural-language keys in snippet definitions; machine-generated property files using arbitrary separators; keys containing locale-specific characters.

Related errors

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