Error Handling

Widgets are placed on dashboards and configured by users, so they have to deal with incomplete configuration, metrics that disappear and unexpected values. This page describes the states a widget should handle, and what MoBro does when a widget fails.

Missing Configuration

When a user adds a widget to a dashboard, none of its fields are configured yet. Widgets should render something useful in this state instead of failing:

• Use defaultValues for fields where a sensible default exists.
• Show the MissingConfigPlaceholder for fields the widget can't work without, such as the metric of a gauge. Use useIsMetricFieldConfigured to check whether a metric has been selected.

src/widgets/example/Example.tsx

import React from 'react'
import {Loading, MissingConfigPlaceholder, useIsMetricFieldConfigured, useMetricField} from '@modbros/dashboard-sdk'

export default function Example() {
  const isConfigured = useIsMetricFieldConfigured({field: 'metric'})
  const channelValue = useMetricField({field: 'metric'})

  if (!isConfigured) {
    return <MissingConfigPlaceholder text="Please select a metric"/>
  }

  if (!channelValue) {
    return <Loading/>
  }

  return <span>{channelValue.value.value}</span>
}

Missing Values

useMetricField returns null until the first value of the metric arrives, and while the metric has no value. Show the Loading indicator or an empty state instead of accessing the value.

Errors in Widgets

MoBro renders every widget within an error boundary. If a widget throws an error while rendering, only this widget fails: instead of the widget, the dashboard shows an error indicator with the error message as tooltip and a button to reset the widget. The widget is also reset automatically when the user changes its configuration.

Throwing an error is therefore a valid way to report configuration the widget can't handle:

src/widgets/example/Example.tsx

import React from 'react'
import {useNumberField} from '@modbros/dashboard-sdk'

export default function Example() {
  const min = useNumberField({field: 'min', defaultValue: 0})
  const max = useNumberField({field: 'max', defaultValue: 100})

  if (min >= max) {
    throw new Error('The maximum must be greater than the minimum.')
  }

  return <span>{min} - {max}</span>
}

caution

Error boundaries only catch errors thrown while rendering. Catch errors in event handlers, effects and promises yourself.

Missing Metrics

A selected metric may not exist anymore, e.g. because the plugin providing it was uninstalled, or because a dashboard was imported on a PC without the plugin. In that case, useMetricField and useMemoizedMetricField throw a MetricDoesNotExistError.

MoBro handles this error: it waits for the metric to reappear, e.g. while the plugin is still starting, and shows the error only if the metric doesn't provide a value within a few seconds. As soon as the metric provides values again, the widget recovers automatically.

The metric hooks also throw an error if the selected metric doesn't match the filters of the field, e.g. after a dashboard was imported.