octobercms/october · error · SystemException

Unknown dimension field specified:

Error message

Unknown dimension field specified: 

What it means

findDimensionFieldByCode() resolves a dimension field by exact code among the fields previously attached with addDimensionField(). It has no non-strict mode and always throws when the code is unknown, because field codes are the only handle the query builder has for selecting field columns.

Source

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

        }

        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
        );

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

        return array_shift($dimension);
    }

    /**
     * Returns code unique for this dimension to be used as a part of a cache key.
     * @return string
     */
    public function getCacheUniqueCode(): string
    {
        $result = $this->getCode() . $this->getDatabaseColumnName();
        foreach ($this->dimensionFields as $field) {
            $result .= $field->getCode();
        }

        return $result;
    }

View on GitHub (pinned to b608633a7e)

Solutions

1. Check which field codes the dimension actually registers (the addDimensionField() calls in the data source) and correct the referencing code
2. Rename the field back or add an alias field with the expected code
3. Migrate persisted widget/filter configuration to the current field codes

Example fix

// before
$field = $dimension->findDimensionFieldByCode('status');

// after
$field = $dimension->findDimensionFieldByCode('oc_field_status');

$fieldCodes = [];
foreach ($fieldsToAdd as $field) {
    $fieldCodes[] = $field->getCode();
    $dimension->addDimensionField($field);
}
// later, when resolving user-supplied field codes:
if (!in_array($requestedFieldCode, $fieldCodes, true)) {
    throw new InvalidArgumentException("Unknown dimension field '{$requestedFieldCode}'");
}

function dimensionFieldExists(ReportDimension $dimension, array $registeredFieldCodes, string $code): bool
{
    return in_array($code, $registeredFieldCodes, true);
}

try {
    $field = $dimension->findDimensionFieldByCode($code);
} catch (SystemException $e) {
    // unknown field code from request/widget config — reject with 400 rather than 500
    return Response::make(['error' => $e->getMessage()], 400);
}

When it happens

Trigger: $dimension->findDimensionFieldByCode('oc_field_status') when no field with that exact code was added via addDimensionField() on this dimension — e.g. a filter or order rule referencing a field the plugin stopped registering.

Common situations: Field codes are also format-constrained (oc_field_ prefix, see validateCode), so a legacy config storing 'status' instead of 'oc_field_status' will miss; plugin versions that rename or drop fields while dashboard widgets retain the old codes; typos in request payloads built by custom front-ends.

Related errors

• Unknown dimension specified:
• The dimension field code cannot be empty.
• Display name cannot be empty.
• The dimension field code must have the oc_field_ prefix
• Unknown dimension type:

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