Because plugins run as dynamic libraries inside the Media Server process, any crash in a plugin crashes the entire Media Server. Although the server automatically restarts, repeating conditions can lead to infinite crash loops.

To create a robust plugin, write your code to contain errors, report anomalies, and continue execution whenever possible.

How to handle common error scenarios

The following table summarizes recommended recovery actions for common plugin error scenarios:

• Internal plugin errors (such as failed invariants)
  Fail an assertion and recover.

• Media Server misbehavior (such as invalid arguments)
  Fail an assertion and recover, typically by returning an error.

• Plugin backend issues
  If the current function can return an error, return an error. Otherwise, or for asynchronous errors, raise a Plugin Diagnostic Event and recover.

• Invalid user data (such as invalid setting values)
  If this is where the data first enters the plugin, return an error. Otherwise, fail an assertion and recover.

Return errors from functions

Most SDK interface functions can return either a valid value or an error containing an error code and message. Use error returns as your primary handling method when a task cannot be completed.

Error handling components

The SDK provides error tools in src/nx/sdk/result.h:

• nx::sdk::ErrorCode: An enum containing standard error codes, including otherError for fallback cases.

• nx::sdk::Error: A helper class combining an ErrorCode with a text message string.

• nx::sdk::Result<Value>: A template class representing either a valid Value or an Error. Most interface methods use this as their return type.

• nx::sdk::error(): A helper function in src/nx/sdk/error that constructs Error objects:

  Error nx::sdk::error(ErrorCode errorCode, std::string errorMessage)

Because Result<Value> converts implicitly from Value and Error, you can return values or errors directly:

Result<int> ISomething::divide(int numerator, int denominator)
{
    if (denominator == 0)
        return error(ErrorCode::invalidParams, "Incorrect number");

    const int value = numerator / denominator;
    return value;
}

Use assertions for unexpected conditions

Standard C/C++ assert() macros disable condition checks in Release builds, allowing invalid states to cause crashes in production.

To prevent this, use the NX_KIT_ASSERT() macro defined in nx/kit/debug.h. In Release builds, NX_KIT_ASSERT() logs the issue without crashing the process. It also evaluates to a boolean value, making inline recovery straightforward.

Example: Assertion with recovery

Result<int> ISomething::divide(int numerator, int denominator)
{
    // Evaluates the condition and logs an assertion if false, without crashing.
    if (!NX_KIT_ASSERT(denominator != 0))
        return error(ErrorCode::invalidParams, "Incorrect number");

    const int value = numerator / denominator;
    return value;
}

Raise Plugin Diagnostic Events

When an error occurs in a plugin backend and you cannot return an error code, raise a Plugin Diagnostic Event. These events feed into the VMS Rules Engine, allowing system administrators to trigger actions, like sending email notifications or any other Action.

Event severity levels

When creating a diagnostic event, select one of the following severity levels:

• Error: A permanent or critical failure that prevents the plugin or a specific operation (such as processing a video frame) from working.

• Warning: An issue occurred, but the plugin recovered or can still operate (for example, a temporary disconnect or low disk space).

• Info: A significant state change occurred that requires administrator awareness.

Event properties

The Media Server automatically assigns the following event properties:

• Analytics Engine ID

• Event timestamp

• Device (Camera) ID, if raised by a DeviceAgent

Assign these properties in your plugin code:

• Level: The severity level (Error, Warning, or Info).

• Caption: A brief summary of the event.

• Description: Additional technical details, such as relevant IDs or context.

How to raise an event

You can raise diagnostic events using the IHandler object supplied by the server:

• nx::sdk::analytics::IEngine::IHandler::handlePluginDiagnosticEvent()

• nx::sdk::analytics::IDeviceAgent::IHandler::handlePluginDiagnosticEvent()

Pass a nx::sdk::IPluginDiagnosticEvent instance to these methods. Use the nx::sdk::PluginDiagnosticEvent helper class to build this object.

If your plugin extends nx::sdk::analytics::Engine or nx::sdk::analytics::DeviceEngine, call the protected helper method directly:

pushPluginDiagnosticEvent(
    nx::sdk::IPluginDiagnosticEvent::Level level,
    std::string caption,
    std::string description);

Best practices for event frequency

Avoid raising diagnostic events repeatedly (such as on every video frame). Frequent events can overwhelm system logs and trigger excessive notifications.

To limit event frequency:

1. Set a boolean flag when an error state occurs for the first time.

2. Raise the diagnostic event once.

3. Clear the flag only when the state resolves or when the DeviceAgent restarts.