octobercms/october · error · SystemException

Unknown dimension specified:

Error message

Unknown dimension specified: 

What it means

ReportDimension::findDimensionByCode() resolves a dimension reference by exact code match against the available dimensions array. With the default $strict = true it throws when no dimension matches; passing strict = false returns null instead. It is the lookup used when resolving dimension codes coming from widget configurations or data-fetch requests.

Source

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

    }

    /**
     * Finds a dimension by its code.
     * @param ReportDimension[] $availableDimensions Specifies the list of available dimensions.
     * @param string $dimensionCode The code of the dimension to find.
     * @param ?bool $strict If true, throws an exception when the dimension cannot be found. Defaults to true.
     * @return ?ReportDimension Returns the found dimension.
     */
    public static function findDimensionByCode(array $availableDimensions, string $dimensionCode, ?bool $strict = true): ?ReportDimension
    {
        $dimension = array_filter(
            $availableDimensions,
            fn($item) => $item->getCode() === $dimensionCode
        );

        if (!count($dimension)) {
            if ($strict) {
                throw new SystemException('Unknown dimension specified: '.$dimensionCode);
            }

            return null;
        }

        return array_shift($dimension);
    }

    /**
     * Finds a dimension field by its code.
     * @param string $dimensionFieldCode
     * @return ReportDimensionField
     */
    public function findDimensionFieldByCode(string $dimensionFieldCode): ReportDimensionField
    {
        $dimension = array_filter(
            $this->dimensionFields,
            fn($item) => $item->getCode() === $dimensionFieldCode

View on GitHub (pinned to b608633a7e)

Solutions

1. Verify the requested code exists in the data source's available dimensions and fix the widget configuration (usually by re-creating or re-saving the widget)
2. Update or migrate the persisted widget config records to the new dimension code
3. If a missing dimension is a tolerable condition, call findDimensionByCode($dims, $code, false) and handle the null return

Example fix

// before
$dimension = ReportDimension::findDimensionByCode($available, $code);

// after (tolerate missing dimension)
$dimension = ReportDimension::findDimensionByCode($available, $code, false);
if (!$dimension) {
    // log and fall back to a default dimension instead of crashing the dashboard
    $dimension = ReportDimension::findDimensionByCode($available, 'date', false);
}

$knownCodes = array_map(fn (ReportDimension $d) => $d->getCode(), $availableDimensions);
if (!in_array($requestedCode, $knownCodes, true)) {
    // unknown code: reject early with a clear message instead of letting the fetch handler throw
    throw new InvalidArgumentException("Unknown dimension code '{$requestedCode}'");
}
$dimension = ReportDimension::findDimensionByCode($availableDimensions, $requestedCode);

function dimensionExists(array $availableDimensions, string $code): bool
{
    foreach ($availableDimensions as $dimension) {
        if ($dimension->getCode() === $code) {
            return true;
        }
    }
    return false;
}

try {
    $dimension = ReportDimension::findDimensionByCode($dims, $code);
} catch (SystemException $e) {
    // widget config references a removed dimension: log, rebuild, or degrade gracefully
    Log::warning($e->getMessage());
    $dimension = null;
}

When it happens

Trigger: ReportDimension::findDimensionByCode($dataSource->getAvailableDimensions(), 'status') when no dimension with code exactly 'status' was registered on the data source — e.g. a widget stored in system_widget_data referencing a dimension the plugin no longer registers.

Common situations: A plugin update renamed or removed a dimension while user dashboards still hold the old code in their persisted widget config; typo in the dimension code in widget config or request payload; restoring a DB dump onto a different plugin version.

Related errors

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

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