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.

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.
• Invalid configuration. All keys must be non-empty strings…
• The dimension field code must have the oc_field_ prefix …
• Unknown dimension field specified:
• Attribute name cannot be empty for

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

Appendix: 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)