octobercms/october · error · SystemException

The dimension metric is already registered:

Error message

The dimension metric is already registered: 

What it means

Dimension metrics are keyed by their code — that code is what widget configurations and fetch requests reference. addDimensionMetric() filters the already-registered metrics by code and throws a SystemException when a metric with the same code is registered twice on the same dimension.

Source

Thrown at modules/dashboard/classes/ReportDimension.php:232

    public function getYearGroupingField(): ?string
    {
        return $this->yearGroupingField;
    }

    /**
     * Registers a dimension metric.
     * @param ReportMetric $metric A metric to add.
     * @return ReportDimension Returns the dimension object for chaining.
     */
    public function addDimensionMetric(ReportMetric $metric): ReportDimension
    {
        $knownMetric = array_filter(
            $this->metrics,
            fn ($item) => $item->getCode() === $metric->getCode()
        );

        if (count($knownMetric)) {
            throw new SystemException('The dimension metric is already registered: ' . $metric->getCode());
        }

        $this->metrics[] = $metric;
        return $this;
    }

    /**
     * A shorthand version of addDimensionMetric.
     * Adds a calculated metric that doesn't work with the database.
     * @param string $displayName Metric display name for the UI.
     * @return ReportDimension Returns the dimension object for chaining.
     */
    public function addCalculatedMetric(string $metricCode, string $displayName): ReportDimension
    {
        return $this->addDimensionMetric(new ReportMetric(
            $metricCode,
            $metricCode,
            $displayName,

View on GitHub (pinned to b608633a7e)

Solutions

1. Make each metric code unique on the dimension — rename the duplicate (e.g. 'total' vs 'refunded_total')
2. Deduplicate the source list by code before registering: array_reduce/array_filter keeping first occurrence
3. If merging lists from multiple sources, key the merged array by metric code so later entries overwrite rather than duplicate

Example fix

// before
$dimension->addDimensionMetric(new ReportMetric('total', 'oc_amount', 'Total', 'sum'));
$dimension->addDimensionMetric(new ReportMetric('total', 'oc_tax', 'Tax', 'sum'));

// after
$dimension->addDimensionMetric(new ReportMetric('total', 'oc_amount', 'Total', 'sum'));
$dimension->addDimensionMetric(new ReportMetric('tax', 'oc_tax', 'Tax', 'sum'));

$registered = [];
foreach ($metrics as $metric) {
    if (in_array($metric->getCode(), $registered, true)) {
        continue; // or log a warning about the duplicate
    }
    $dimension->addDimensionMetric($metric);
    $registered[] = $metric->getCode();
}

try {
    $dimension->addDimensionMetric($metric);
} catch (SystemException $e) {
    // duplicate code — log and continue registering the rest
    Log::warning('Skipped duplicate dimension metric: ' . $metric->getCode());
}

When it happens

Trigger: Calling $dimension->addDimensionMetric(new ReportMetric('total', ...)) twice, or looping over a config array that contains two ReportMetric definitions with $code = 'total' for the same dimension.

Common situations: Copy-pasted metric definitions with the code not updated; merging metric lists from multiple plugins/traits that both define common codes like 'total' or 'count'; dynamic metric generation that re-runs during a request (e.g. re-registration in a loop or on retry).

Related errors

• Unknown dimension type:
• Date dimensions cannot have fields.
• Unknown dimension specified:
• Unknown dimension field specified:
• Invalid configuration. All keys must be non-empty strings an

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