octobercms/october · error · SystemException

The provided class is not a report widget:

Error message

The provided class is not a report widget: 

What it means

StaticReportWidgetContainer::makeWidget() instantiates a widget class from dashboard configuration and guards it with is_subclass_of($widgetClass, ReportWidgetBase::class); anything else throws SystemException('The provided class is not a report widget: <class>'). The class name comes from widget configuration in a dashboard definition, so the error means the configured class either does not exist in that case or is not a ReportWidgetBase subclass (note: is_subclass_of on a non-existent class returns false without autoload success).

Source

Thrown at modules/dashboard/classes/StaticReportWidgetContainer.php:50

     * Widget classes must extend Backend\Classes\ReportWidgetBase.
     * @param array $widgetConfig Widget properties
     * @return string Returns the rendered widget string
     */
    public function renderWidget(string $widgetClass, array $widgetConfig): string
    {
        $widget = $this->makeWidget($widgetClass);
        $widget->setProperties($widgetConfig);

        return $widget->render();
    }

    /**
     * makeWidget
     */
    private function makeWidget(string $widgetClass)
    {
        if (!is_subclass_of($widgetClass, ReportWidgetBase::class)) {
            throw new SystemException("The provided class is not a report widget: " . $widgetClass);
        }

        return new $widgetClass($this->controller);
    }
}

View on GitHub (pinned to b608633a7e)

Solutions

1. Point the widget config at a class that extends Dashboard\ReportWidgets\ReportWidgetBase (or the module's ReportWidgetBase), fully namespaced.
2. Fix typos/namespace changes in the dashboard definition; after renaming a widget class, update saved dashboard records or reset the dashboard to defaults.
3. Ensure the plugin providing the widget is installed and enabled so the class is autoloadable.
4. If stale user dashboards are the issue, reset the affected user's dashboard configuration (Dashboard model / user preferences).

Example fix

// before (dashboard definition)
widgets:
  sales: SalesSummary // not a report widget class / unnamespaced

// after
widgets:
  sales: \MyPlugin\ReportWidgets\SalesSummary

$widgetClass = $widgetConfig['class'] ?? null;
if (!is_string($widgetClass) || !class_exists($widgetClass) || !is_subclass_of($widgetClass, ReportWidgetBase::class)) {
    throw new ApplicationException("Dashboard widget '{$widgetClass}' is not available.");
}
$container->renderWidget($widgetClass, $widgetConfig);

function isReportWidgetClass(mixed $class): bool
{
    return is_string($class) && class_exists($class) && is_subclass_of($class, ReportWidgetBase::class);
}

try {
    return $container->renderWidget($class, $config);
} catch (SystemException $e) {
    if (str_contains($e->getMessage(), 'not a report widget')) {
        Log::warning($e->getMessage());
        return '<!-- widget unavailable -->'; // graceful placeholder on a dashboard
    }
    throw $e;
}

When it happens

Trigger: A dashboard definition (DB-stored or default) whose static widget entry names a plain class, a controller, or a namespaced class string with a typo; referencing a widget class that moved namespaces between versions; widget class present in a plugin that is disabled or not loaded.

Common situations: Plugin disabled/removed but the user's saved dashboard still references its widget; copy-pasting a widget alias without registering it; YAML/JSON dashboard config using the wrong key so a non-class string (e.g. a partial name) is read as the class.

Related errors

• Unknown widget report interval {$widgetInterval}
• The provided class is not a report data source:
• The provided class is not a dashboard widget: {$className}
• Custom widget class [{$widgetClass}] is not set.
• Custom widget class [{$widgetClass}] is not set.

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