{"record":{"id":"915d63fee2a5325e","repo":"octobercms/october","slug":"unknown-dimension-specified","errorCode":null,"errorMessage":"Unknown dimension specified: ","messagePattern":"Unknown dimension specified: ","errorType":"exception","errorClass":"SystemException","httpStatus":null,"severity":"error","filePath":"modules/dashboard/classes/ReportDimension.php","lineNumber":343,"sourceCode":"    }\n\n    /**\n     * Finds a dimension by its code.\n     * @param ReportDimension[] $availableDimensions Specifies the list of available dimensions.\n     * @param string $dimensionCode The code of the dimension to find.\n     * @param ?bool $strict If true, throws an exception when the dimension cannot be found. Defaults to true.\n     * @return ?ReportDimension Returns the found dimension.\n     */\n    public static function findDimensionByCode(array $availableDimensions, string $dimensionCode, ?bool $strict = true): ?ReportDimension\n    {\n        $dimension = array_filter(\n            $availableDimensions,\n            fn($item) => $item->getCode() === $dimensionCode\n        );\n\n        if (!count($dimension)) {\n            if ($strict) {\n                throw new SystemException('Unknown dimension specified: '.$dimensionCode);\n            }\n\n            return null;\n        }\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","sourceCodeStart":325,"sourceCodeEnd":361,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/dashboard/classes/ReportDimension.php#L325-L361","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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)","Update or migrate the persisted widget config records to the new dimension code","If a missing dimension is a tolerable condition, call findDimensionByCode($dims, $code, false) and handle the null return"],"exampleFix":"// before\n$dimension = ReportDimension::findDimensionByCode($available, $code);\n\n// after (tolerate missing dimension)\n$dimension = ReportDimension::findDimensionByCode($available, $code, false);\nif (!$dimension) {\n    // log and fall back to a default dimension instead of crashing the dashboard\n    $dimension = ReportDimension::findDimensionByCode($available, 'date', false);\n}","handlingStrategy":"validation","validationCode":"$knownCodes = array_map(fn (ReportDimension $d) => $d->getCode(), $availableDimensions);\nif (!in_array($requestedCode, $knownCodes, true)) {\n    // unknown code: reject early with a clear message instead of letting the fetch handler throw\n    throw new InvalidArgumentException(\"Unknown dimension code '{$requestedCode}'\");\n}\n$dimension = ReportDimension::findDimensionByCode($availableDimensions, $requestedCode);","typeGuard":"function dimensionExists(array $availableDimensions, string $code): bool\n{\n    foreach ($availableDimensions as $dimension) {\n        if ($dimension->getCode() === $code) {\n            return true;\n        }\n    }\n    return false;\n}","tryCatchPattern":"try {\n    $dimension = ReportDimension::findDimensionByCode($dims, $code);\n} catch (SystemException $e) {\n    // widget config references a removed dimension: log, rebuild, or degrade gracefully\n    Log::warning($e->getMessage());\n    $dimension = null;\n}","preventionTips":["Expose the list of registered dimension codes in your plugin docs so integrators reference valid codes","When renaming dimensions, ship a migration that updates persisted widget configs","Prefer findDimensionByCode(..., strict: false) plus an explicit null check at trust boundaries (request input)"],"tags":["php","dashboard","report","dimension","lookup","widget-config"],"backgroundTag":"entity-not-found","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}