octobercms/october · error · SystemException

Unknown dimension type:

Error message

Unknown dimension type: 

What it means

ReportDimension's constructor parses dimension codes written as 'type@code'. The only recognized type prefix is 'indicator' (ReportDimension::TYPE_INDICATOR); any other prefix segment before the '@' throws a SystemException because no other dimension type is implemented. Codes without '@' (plain dimensions) or with more than one '@' never set a type and never trigger this error.

Source

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

            throw new SystemException('The database column name cannot be empty.');
        }

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

        $knownTypes = [
            ReportDimension::TYPE_INDICATOR
        ];

        $dimensionType = null;
        $codeParts = explode('@', $code);
        if (count($codeParts) === 2) {
            $dimensionType = $codeParts[0];
        }

        if ($dimensionType !== null && !in_array($dimensionType, $knownTypes)) {
            throw new SystemException('Unknown dimension type: ' . $dimensionType);
        }

        $this->code = $code;
        $this->databaseColumnName = $databaseColumnName;
        $this->displayName = $displayName;
        $this->dimensionType = $dimensionType;
        $this->labelColumnName = $labelColumnName;
    }

    /**
     * Adds a field to this dimension.
     * @param ReportDimensionField $field Specifies the field to add.
     * @return $this Returns the dimension object for method chaining.
     */
    public function addDimensionField(ReportDimensionField $field): ReportDimension
    {
        if ($this->isDate()) {
            throw new SystemException('Date dimensions cannot have fields.');

View on GitHub (pinned to b608633a7e)

Solutions

1. Remove the unrecognized prefix and use a plain code such as 'orders' — most dimensions need no type prefix
2. If you are building an indicator dimension, build the code as ReportDimension::TYPE_INDICATOR . '@yourCode' so the prefix always matches the constant
3. Check the TYPE_XXX constants on ReportDimension (currently only TYPE_INDICATOR = 'indicator') before composing a prefixed code

Example fix

// before
$dimension = new ReportDimension('metric@revenue', 'oc_revenue_id', 'Revenue');

// after (plain dimension, no prefix)
$dimension = new ReportDimension('revenue', 'oc_revenue_id', 'Revenue');

// or, for an indicator dimension
$code = ReportDimension::TYPE_INDICATOR . '@revenue';
$dimension = new ReportDimension($code, 'oc_revenue_id', 'Revenue');

$knownTypes = [ReportDimension::TYPE_INDICATOR]; // extend if new TYPE_XXX appear
$parts = explode('@', $code);
if (count($parts) === 2 && !in_array($parts[0], $knownTypes, true)) {
    throw new InvalidArgumentException(
        "Unsupported dimension type '{$parts[0]}'. Use no prefix or one of: " . implode(', ', $knownTypes)
    );
}

function dimensionCodeHasKnownType(string $code): bool
{
    $parts = explode('@', $code);
    return count($parts) !== 2 || in_array($parts[0], [ReportDimension::TYPE_INDICATOR], true);
}

When it happens

Trigger: Constructing a dimension whose code contains exactly one '@' and a non-'indicator' prefix, e.g. new ReportDimension('status@orders', 'id', 'Status') or new ReportDimension('metric@revenue', ...). Note 'a@b@c' (two '@') yields 3 explode parts, so dimensionType stays null and no exception is thrown.

Common situations: Typo'd or wrong-case prefixes ('Indicator@', 'indicators@' — the check is case-sensitive), copying a prefix convention from another plugin, or assuming a 'date@' or 'metric@' dimension type exists. Only TYPE_INDICATOR is defined on ReportDimension.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Date dimensions cannot have fields.
• The dimension metric is already registered:
• 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/10c9b5adfd7ef24e. Report an issue: GitHub.