octobercms/october · error · SystemException

The metric code cannot be empty.

Error message

The metric code cannot be empty.

What it means

ReportMetric's constructor requires a non-empty metric code, since the code identifies the metric in widget configurations, fetch requests, and cache keys. An empty string throws before any other validation of the metric definition.

Source

Thrown at modules/dashboard/classes/ReportMetric.php:62

    /**
     * @var ?callable Server-side formatter for human-readable display values.
     */
    private $displayFormatter;

    /**
     * __construct a new metric instance.
     * @param string $code Specifies the metric referral code.
     * @param string $databaseColumnName Specifies the column name in the data source table.
     * @param string $displayName Specifies the metric name used in reports.
     * @param string $aggregateFunction Specifies the aggregate function for the metric.
     * @param ?array $intlFormatOptions Client-side formatting options, compatible with the Intl.NumberFormat() constructor options argument.
     * Skip the argument to use the default formatting options.
     */
    public function __construct(string $code, string $databaseColumnName, string $displayName, string $aggregateFunction, ?array $intlFormatOptions = null)
    {
        if (!strlen($code)) {
            throw new SystemException('The metric code cannot be empty.');
        }

        if (!preg_match('/^[a-z][a-z0-9_]+$/i', $code)) {
            throw new SystemException('The metric code can only contain Latin letters, numbers and underscore. The first character must be a letter');
        }

        if (!strlen($databaseColumnName)) {
            throw new SystemException('The database column name cannot be empty.');
        }

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

        if (!strlen($aggregateFunction)) {
            throw new SystemException('The aggregate function cannot be empty.');
        }

View on GitHub (pinned to b608633a7e)

Solutions

1. Ensure every metric definition carries a unique non-empty code (e.g. 'total', 'avg_order')
2. Validate config-derived codes with trim() !== '' before constructing metrics
3. Fail loudly at config load time so bad definitions are caught during development, not at render time

Example fix

// before
$metric = new ReportMetric($config['code'] ?? '', 'oc_amount', 'Total', 'sum');

// after
$code = trim((string) ($config['code'] ?? ''));
if ($code === '') {
    throw new InvalidArgumentException('Metric code missing in config for metric: ' . ($config['name'] ?? '?'));
}
$metric = new ReportMetric($code, 'oc_amount', 'Total', 'sum');

$code = trim((string) ($config['code'] ?? ''));
if ($code === '') {
    throw new InvalidArgumentException('Metric code missing for metric: ' . ($config['name'] ?? '?'));
}
$metric = new ReportMetric($code, $config['column'], $config['name'], $config['aggregate']);

When it happens

Trigger: new ReportMetric('', 'oc_amount', 'Total', 'sum') — any construction where the first argument has zero length.

Common situations: Config-driven metric lists where a 'code' key is missing or resolves to ''; copy-paste metric definitions left with an empty placeholder; whitespace-only codes (' ' passes strlen but fails the following regex, so trim first).

Related errors

• The dimension metric is already registered:
• Invalid configuration. All keys must be non-empty strings an
• The dimension field code cannot be empty.
• Display name cannot be empty.
• Invalid data attribute type. Supported types:

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