octobercms/october · error · SystemException

Data source [{$dataSourceClass}] class is not registered.

Error message

Data source [{$dataSourceClass}] class is not registered.

What it means

Dash::makeDataSource resolves a report data source class through DashManager::getDataSource, which only knows classes registered with DashManager::registerDataSourceClass. The dashboard module registers three built-ins (SystemReportDataSource, CmsReportDataSource, CmsStatusDataSource) in its ServiceProvider; plugins add their own. A class not in that registry returns null and this SystemException is thrown.

Source

Thrown at modules/dashboard/widgets/Dash.php:637

        $result = $widget->runHandler(
            $widgetConfig,
            $handlerName,
            $extraData
        );

        return $result;
    }

    /**
     * makeDataSource
     */
    protected function makeDataSource(string $dataSourceClass): ReportDataSourceBase
    {
        $dataSourceManager = DashManager::instance();
        $dataSource = $dataSourceManager->getDataSource($dataSourceClass);
        if (!$dataSource) {
            throw new SystemException("Data source [{$dataSourceClass}] class is not registered.");
        }

        return $dataSource;
    }

    /**
     * findDimension
     */
    protected function findDimension(ReportDataSourceBase $dataSource, string $dimensionCode, bool $strict): ?ReportDimension
    {
        return ReportDimension::findDimensionByCode($dataSource->getAvailableDimensions(), $dimensionCode, $strict);
    }

    /**
     * listAllMetrics
     */
    protected function listAllMetrics(ReportDataSourceBase $dataSource, string $dimensionCode): array
    {

View on GitHub (pinned to b608633a7e)

Solutions

1. Register the data source class with DashManager::instance()->registerDataSourceClass(MyDataSource::class, 'My Data') (or via your plugin's registration hook) so getDataSource can find it.
2. Fix the dataSource value in the widget configuration to the exact fully qualified class name that was registered.
3. Install/enable the plugin that provides the data source, then reload the dashboard.
4. List registered sources with DashManager::instance()->listDataSourceClasses() to verify what the manager actually knows.

Example fix

// before - widget config
{ "dataSource": "MyPlugin\Report\DataSource" }

// after
class MyPlugin extends PluginBase
{
    public function boot()
    {
        \Dashboard\Classes\DashManager::instance()
            ->registerDataSourceClass(OrdersDataSource::class, 'Orders');
    }
}
// widget config: { "dataSource": "MyPlugin\Report\OrdersDataSource" }

$manager = \Dashboard\Classes\DashManager::instance();
if (!array_key_exists($dataSourceClass, $manager->listDataSourceClasses())) {
    throw new \ValidationException(['dataSource' => "Data source {$dataSourceClass} is not registered"]);
}

function isRegisteredDataSource(string $class): bool
{
    return array_key_exists(
        $class,
        \Dashboard\Classes\DashManager::instance()->listDataSourceClasses()
    );
}

try {
    $source = $this->makeDataSource($class);
} catch (\SystemException $e) {
    // unregistered source: surface which class failed and continue with other reports
    \Log::warning($e->getMessage());
    return null;
}

When it happens

Trigger: A report widget configuration whose dataSource property names a class that was never registered; referencing a custom data source in a widget config while the plugin that registers it is disabled or not yet installed; misspelled or renamed data source class in a saved dashboard definition after a refactor.

Common situations: Deploying a dashboard definition from one environment to another where the data-source plugin is missing; renaming a data source class without updating saved dashboard definitions in the database; copy-pasting example configs from docs that reference a plugin class you have not installed.

Related errors

• Widget class [{$widgetClass}] not registered.
• Widget class [{$widgetClass}] not registered.
• backend::lang.widget.not_registered
• Report [{$reportName}] is not registered
• Report widget data source class is not set

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