octobercms/october · error · SystemException

The dimension field code cannot be empty.

Error message

The dimension field code cannot be empty.

What it means

ReportDimensionField's constructor requires a non-empty field code, because the code is the identifier used in queries, filters, and cache keys. An empty string throws immediately before any other validation runs.

Source

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

    /**
     * Creates a new dimension field.
     * @param string $code Specifies the field referral code.
     * @param string $displayName Specifies the field name to use in reports.
     * @param ?string $columnName Optional database column name for filtering or sorting.
     * Provide the column name if the column added to the SELECT statement cannot be
     * used directly, such as when it involves an aggregation function.
     * @param bool $sortable Specifies if the field is sortable.
     * @param bool $filterable Specifies if the field is filterable.
     */
    public function __construct(
        string $code,
        string $displayName,
        ?string $columnName = null,
        bool $sortable = false,
        bool $filterable = false
    ) {
        if (!strlen($code)) {
            throw new SystemException('The dimension field code cannot be empty.');
        }

        self::validateCode($code);

        if (!strlen($displayName)) {
            throw new SystemException('Display name cannot be empty.');
        }

        $this->displayName = $displayName;
        $this->sortable = $sortable;
        $this->filterable = $filterable;
        $this->code = $code;
        $this->columnName = $columnName;
    }

    /**
     * Returns the dimension field code.
     * @return string Returns the dimension field code.

View on GitHub (pinned to b608633a7e)

Solutions

1. Make sure the code is a non-empty string built from real data (e.g. 'oc_field_' . $key)
2. Default missing config keys to a generated code instead of ''
3. Trim and validate config-derived codes before constructing the field

Example fix

// before
$field = new ReportDimensionField($config['code'] ?? '', $config['name']);

// after
$field = new ReportDimensionField(
    'oc_field_' . ($config['key'] ?? $config['name']),
    $config['name']
);

$code = trim((string) ($config['code'] ?? ''));
if ($code === '') {
    throw new InvalidArgumentException('Dimension field code missing in config');
}
$field = new ReportDimensionField('oc_field_' . $code, $config['name']);

When it happens

Trigger: new ReportDimensionField('', 'Status') or new ReportDimensionField($missingVar ?? '', 'Status') — any constructor call where the $code argument has zero length.

Common situations: Dynamically building fields from configuration arrays where a 'code' key is absent and null coalesces to ''; whitespace-only codes (note: strlen(' ') is 1, so ' ' passes this check but fails the later regex); copy-paste templates left with a placeholder code.

Related errors

• Display name cannot be empty.
• Unknown dimension field specified:
• Invalid configuration. All keys must be non-empty strings an
• The dimension field code must have the oc_field_ prefix
• Unknown dimension type:

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