Error Handling

Error handling in MoBro plugins follows the same practices as in other .NET applications: catch and handle all errors that don't render the plugin inoperable, and let MoBro know about the ones that do.

How MoBro Handles Errors

Situation	Result
An exception is thrown by the constructor, Init() or InitAsync()	The plugin is stopped and its state changes to Error.
An exception escapes a scheduled task	The plugin is stopped and its state changes to Error.
An exception escapes an action handler	The plugin may be stopped.
IMoBroService.Error(...) is called	The plugin is stopped and its state changes to Error.
An invalid item is registered	The item is skipped and a warning is logged.
A value is pushed for a metric that isn't registered	The value is ignored.

When a plugin is stopped due to an error, MoBro logs the exception and displays its message to the user. The plugin stays in the Error state until it is started again, e.g. when the user changes its settings.

Choosing the Right Approach

---

Errors in Scheduled Tasks

caution

Scheduled tasks are the most common source of unexpectedly stopped plugins. Any exception escaping a task passed to IMoBroScheduler.Interval, Cron or OneOff stops the entire plugin.
A single failed HTTP request takes the plugin offline unless it is caught.

Catch expected failures inside the task and only let exceptions escape if the plugin can't continue:

private void UpdateMetrics()
{
  try
  {
    var rates = _apiClient.GetExchangeRates();
    _mobro.UpdateMetricValue("usd_eur", rates.UsdEur);
  }
  catch (HttpRequestException e)
  {
    // Temporary network issue => keep the last value and try again on the next execution
    _logger.LogWarning(e, "Failed to fetch exchange rates");
  }
}

---

Missing Dependencies

If the plugin depends on external software (declared in the dependencies of the plugin configuration), report its status instead of throwing an exception. This lets MoBro show the user what's missing, while the plugin keeps running and recovers once the dependency becomes available:

private void UpdateMetrics()
{
  if (!Aida64.IsRunning())
  {
    _mobro.SetDependencyStatus("aida64", DependencyStatus.Missing);
    return;
  }

  _mobro.SetDependencyStatus("aida64", DependencyStatus.Ok);
  // read and update the metric values
}

If the plugin can't work at all without the dependency, throw a PluginDependencyException instead.

---

Manual Error Notification

The IMoBroService provides the Error functions to notify MoBro about unrecoverable errors without throwing an exception.
Calling these functions has the same effect as an unhandled exception: the error is logged, the plugin is stopped and its state is set to Error with the provided message.

---

Plugin Exceptions

The SDK includes several exception classes to convey additional error details to MoBro.

PluginException

Represents a generic error that occurs during plugin execution. All other plugin exceptions derive from it.

Parameters

Name	Type	Description
message	string?	A descriptive error message.
innerException	Exception?	An inner exception providing additional details.

Additional details are added using the AddDetail(key, value) function and are available in the Details dictionary.

Example

try
{
  InitializeSensorLibrary();
}
catch (Exception e)
{
  throw new PluginException("Failed to initialize the sensor library", e)
    .AddDetail("library_version", SensorLibrary.Version);
}

---

PluginDependencyException

Indicates an error in an external dependency (e.g., another program or a web API) that prevents the plugin from working. MoBro reports it as a problem with an external dependency.

Parameters

Name	Type	Description
message	string?	A descriptive error message.
innerException	Exception?	An inner exception providing additional details.

Example

try
{
  _connection = Aida64.OpenSharedMemory();
}
catch (Exception e)
{
  throw new PluginDependencyException("Failed to connect to AIDA64: " + e.Message, e);
}

---

PluginSettingsException

Indicates that a required setting is missing or a settings value is invalid. MoBro reports it as a settings error for the given field.

tip

IMoBroSettings.GetValue<T>(string) automatically throws a PluginSettingsException if a setting has no value or can't be converted.

Parameters

Name	Type	Description
field	string?	The name of the settings field causing the error.
message	string?	A descriptive error message.
innerException	Exception?	An inner exception providing additional details.

Example

var apiKey = _settings.GetValue<string>("api_key");
if (apiKey.Length != 32)
{
  throw new PluginSettingsException("api_key", "The API key must be 32 characters long", null);
}

---

Exceptions Thrown by the SDK

The following exceptions are thrown by the SDK itself. They usually indicate a bug in the plugin and appear in the logs.

Exception	Thrown when
MetricValueValidationException	A value passed to UpdateMetricValue(s) doesn't match the metric's MetricValueType. Contains the ID of the metric.
MoBroItemValidationException	An invalid item is registered while running locally. Contains the ID of the item and the name of the invalid field.