{"record":{"id":"c35de5c0f87b1337","repo":"octobercms/october","slug":"unknown-dimension-field-specified","errorCode":null,"errorMessage":"Unknown dimension field specified: ","messagePattern":"Unknown dimension field specified: ","errorType":"exception","errorClass":"SystemException","httpStatus":null,"severity":"error","filePath":"modules/dashboard/classes/ReportDimension.php","lineNumber":365,"sourceCode":"        }\n\n        return array_shift($dimension);\n    }\n\n    /**\n     * Finds a dimension field by its code.\n     * @param string $dimensionFieldCode\n     * @return ReportDimensionField\n     */\n    public function findDimensionFieldByCode(string $dimensionFieldCode): ReportDimensionField\n    {\n        $dimension = array_filter(\n            $this->dimensionFields,\n            fn($item) => $item->getCode() === $dimensionFieldCode\n        );\n\n        if (!count($dimension)) {\n            throw new SystemException('Unknown dimension field specified: '.$dimensionFieldCode);\n        }\n\n        return array_shift($dimension);\n    }\n\n    /**\n     * Returns code unique for this dimension to be used as a part of a cache key.\n     * @return string\n     */\n    public function getCacheUniqueCode(): string\n    {\n        $result = $this->getCode() . $this->getDatabaseColumnName();\n        foreach ($this->dimensionFields as $field) {\n            $result .= $field->getCode();\n        }\n\n        return $result;\n    }","sourceCodeStart":347,"sourceCodeEnd":383,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/dashboard/classes/ReportDimension.php#L347-L383","documentation":"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.","triggerScenarios":"$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.","commonSituations":"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.","solutions":["Check which field codes the dimension actually registers (the addDimensionField() calls in the data source) and correct the referencing code","Rename the field back or add an alias field with the expected code","Migrate persisted widget/filter configuration to the current field codes"],"exampleFix":"// before\n$field = $dimension->findDimensionFieldByCode('status');\n\n// after\n$field = $dimension->findDimensionFieldByCode('oc_field_status');","handlingStrategy":"validation","validationCode":"$fieldCodes = [];\nforeach ($fieldsToAdd as $field) {\n    $fieldCodes[] = $field->getCode();\n    $dimension->addDimensionField($field);\n}\n// later, when resolving user-supplied field codes:\nif (!in_array($requestedFieldCode, $fieldCodes, true)) {\n    throw new InvalidArgumentException(\"Unknown dimension field '{$requestedFieldCode}'\");\n}","typeGuard":"function dimensionFieldExists(ReportDimension $dimension, array $registeredFieldCodes, string $code): bool\n{\n    return in_array($code, $registeredFieldCodes, true);\n}","tryCatchPattern":"try {\n    $field = $dimension->findDimensionFieldByCode($code);\n} catch (SystemException $e) {\n    // unknown field code from request/widget config — reject with 400 rather than 500\n    return Response::make(['error' => $e->getMessage()], 400);\n}","preventionTips":["Validate user-supplied field codes against the codes you actually registered before resolving them","Remember field codes must match the oc_field_ pattern — legacy unprefixed codes will never resolve","Keep a single source of truth mapping field codes to definitions so front-end and backend cannot drift"],"tags":["php","dashboard","report","dimension","field","lookup"],"backgroundTag":"entity-not-found","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}