octobercms/october · error · SystemException

The dimension field code must have the oc_field_ prefix

Error message

The dimension field code must have the oc_field_ prefix
                and can only contain Latin letters, numbers and underscores.

What it means

validateCode() enforces the field code pattern ^oc_field_[a-z][a-zA-Z0-9_]*$: the literal 'oc_field_' prefix, then a lowercase letter, then any mix of letters (either case), digits, and underscores. It runs both from the ReportDimensionField constructor and from ReportDimensionFilter when filtering by a dimension field, so the same rule applies everywhere field codes appear.

Source

Thrown at modules/dashboard/classes/ReportDimensionField.php:111

    }

    /**
     * Returns the database column name if it was provided in the constructor.
     * @return ?string
     */
    public function getColumnName(): ?string
    {
        return $this->columnName;
    }

    /**
     * Validates a dimension field code.
     * @throws SystemException if the code is invalid.
     */
    public static function validateCode(string $code)
    {
        if (!preg_match('/^oc_field_[a-z][a-zA-Z0-9_]*$/', $code)) {
            throw new SystemException('The dimension field code must have the oc_field_ prefix
                and can only contain Latin letters, numbers and underscores.');
        }
    }

    /**
     * Determines if the field is sortable
     * @return bool Returns true if the field is sortable.
     */
    public function getIsSortable()
    {
        return $this->sortable;
    }

    /**
     * Determines if the field is filterable
     * @return bool Returns true if the field is filterable
     */
    public function getIsFilterable()

View on GitHub (pinned to b608633a7e)

Solutions

1. Prefix the code with oc_field_ and make the first character after the prefix a lowercase letter: oc_field_status, oc_field_orderStatus are valid
2. For auto-generated codes, normalize first: lcfirst($name) after stripping invalid characters
3. Remember only the FIRST character must be lowercase — subsequent characters may be uppercase or digits

Example fix

// before
$field = new ReportDimensionField('Status', 'Status');

// after
$field = new ReportDimensionField('oc_field_status', 'Status');

$code = 'oc_field_' . lcfirst(preg_replace('/[^a-zA-Z0-9_]/', '', $rawName));
if (!ReportDimensionField::isValidCode($code)) { // see typeGuard
    throw new InvalidArgumentException("Invalid dimension field code '{$code}'");
}

function isValidDimensionFieldCode(string $code): bool
{
    return (bool) preg_match('/^oc_field_[a-z][a-zA-Z0-9_]*$/', $code);
}

When it happens

Trigger: Codes like 'status' (no prefix), 'oc_field_Status' (first character after the prefix is uppercase), 'oc_field_1status' (starts with a digit), 'oc_field_' (nothing after the prefix), or 'oc_field_my-field' (hyphen) all fail preg_match and throw.

Common situations: Migrating legacy field identifiers into the oc_field_ namespace; machine-generated codes that start with a digit; assuming camelCase is allowed everywhere (only allowed after the first character — the character right after the prefix must be lowercase).

Related errors

• Unknown dimension field specified:
• The dimension field code cannot be empty.
• Display name cannot be empty.
• The metric code can only contain Latin letters, numbers and
• Unknown dimension type:

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