octobercms/october · error · SystemException

The display name cannot be empty.

Error message

The display name cannot be empty.

What it means

The ReportMetric constructor requires a non-empty human-readable $displayName and throws SystemException when strlen($displayName) is 0. The display name is what the dashboard UI shows for the metric in widget headers, tables and charts, so an empty label breaks rendering. Like the other constructor guards, this fails fast at data-source definition time instead of producing a half-configured metric later. Only '' triggers it; '0' passes.

Source

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

     * @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.');
        }

        $knownAggregateFunctions = [
            self::AGGREGATE_SUM,
            self::AGGREGATE_AVG,
            self::AGGREGATE_MIN,
            self::AGGREGATE_MAX,
            self::AGGREGATE_COUNT,
            self::AGGREGATE_NONE,
            self::AGGREGATE_COUNT_DISTINCT,
            self::AGGREGATE_COUNT_DISTINCT_NOT_NULL
        ];

        if (!in_array($aggregateFunction, $knownAggregateFunctions)) {

View on GitHub (pinned to b608633a7e)

Solutions

1. Supply a non-empty display string as the 3rd argument, e.g. new ReportMetric('avg_rating', 'rating', 'Average rating', ReportMetric::AGGREGATE_AVG).
2. If using localization, make sure the lang key exists and __() returns a real string (check the lang file for typos in the key).
3. Add the missing 'label' key to the metric definition array when metrics are config-driven.
4. When localizing, guard empty translations during development: $label = __($key) ?: ucfirst(str_replace('_', ' ', $code));

Example fix

// before
new ReportMetric('avg_rating', 'rating', '', ReportMetric::AGGREGATE_AVG);

// after
new ReportMetric('avg_rating', 'rating', 'Average rating', ReportMetric::AGGREGATE_AVG);

$label = __($langKey) ?: ucfirst(str_replace('_', ' ', $code));
if (!strlen($label)) {
    $label = ucfirst($code);
}
$metric = new ReportMetric($code, $column, $label, $aggregate);

When it happens

Trigger: Calling `new ReportMetric($code, $column, '', 'avg')` — typically the 3rd argument is forgotten when developers copy a shorter constructor call, or a localization helper (e.g. __() on a missing lang key returning '') yields an empty string.

Common situations: Adding a new metric in a hurry and skipping the label; passing a translation key that does not exist in the lang file so the __() call returns empty; building metrics from a config array missing the 'label'/'name' key.

Related errors

• The database column name cannot be empty.
• The aggregate function cannot be empty.
• The aggregate function is not supported:
• Unknown metric:
• Trying to get selected row without a popup reference.

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