Skip to main content

Error reporting

Unhandled / handled exceptions​

For handled exceptions, use a try/catch scheme with the reportError API​

Report handled errors with optional structured data and labels. Choose one variant per error event — each call generates a single error report.

Basic error reporting:

try {
throw StateError('state error try catch');
} catch (error, stackTrace) {
if (error is StateError) {
await CxFlutterPlugin.reportError(
error,
null,
stackTrace.toString(),
);
}
}

With structured data:

try {
throw StateError('payment failed');
} catch (error, stackTrace) {
await CxFlutterPlugin.reportError(
error,
{'orderId': 'ORD-123', 'amount': 99.99},
stackTrace.toString(),
);
}

With data and labels:

try {
throw StateError('payment failed');
} catch (error, stackTrace) {
await CxFlutterPlugin.reportError(
error,
{'orderId': 'ORD-123', 'amount': 99.99},
stackTrace.toString(),
labels: {'team': 'payments', 'severity': 'high'},
);
}

⚠️ Platform note: reportError(message, data, '') (empty stack trace) attaches data on iOS only — the Android native SDK has no data-only entry point, so data is dropped on Android in that shape. Always supply a stack trace when you need attributes attached cross-platform.

For unhandled exceptions​

From version 0.21.0, once initSdk completes, the plugin reports unhandled errors automatically. You don't write any handler code. This covers:

  • Errors the Flutter framework catches, such as exceptions thrown in build, layout, paint, or a gesture callback.
  • Errors that escape every zone, such as a failed Future or compute() call that nothing awaits or catches.

These are reported as errors, not crashes, because an unhandled Dart error doesn't stop the app. Errors Flutter marks as silent, such as a failed image load, are not reported. When the same error repeats, for example on every frame, it is reported at most once every 5 seconds.

To turn this off, set errors to false in instrumentations. This also turns off native crash reporting and reportError:

CXExporterOptions(
// ...
instrumentations: {'errors': false},
);
Note

If you set FlutterError.onError or PlatformDispatcher.instance.onError before calling initSdk, your handler still runs after the plugin reports the error. If your handler also calls reportError, or passes the error to a runZonedGuarded handler that does, remove that path, or each error is reported twice. A handler you set after initSdk replaces the plugin's.

Errors caught by a runZonedGuarded handler don't reach the plugin. If you use runZonedGuarded, report from its handler:

void main() {
runZonedGuarded(() {
runApp(const MyApp());
}, (error, stackTrace) {
CxFlutterPlugin.reportError(error, null, stackTrace.toString());
});
}

Dart errors that happen before initSdk completes are not reported.

Custom log​

await CxFlutterPlugin.log(CxLogSeverity.error, 'this is an error', {'fruit': 'banna', 'price': 1.30});

Views​

To monitor page / views, report the current screen with setView:

await CxFlutterPlugin.setView(viewName);

Each setView also drives the SDK's product-analytics fields on the emitted RUM events: view_number (a per-session counter that increments on each unique view change) and isNavigationEvent. These are owned and computed by the native SDK — you only need to report the view.

Automatic view tracking​

Instead of calling setView in every page, drop CxNavigatorObserver into your app's navigator and route changes are tracked for you:

MaterialApp(
navigatorObservers: [CxNavigatorObserver()],
// ...
);

Only PageRoutes are tracked (dialogs, bottom sheets and popups are not treated as a screen change). The view name is taken from RouteSettings.name, so name your routes:

MaterialPageRoute(
settings: const RouteSettings(name: 'Cart'),
builder: (_) => const CartPage(),
);

Unnamed routes are skipped. To derive the name differently (or skip a route by returning null), pass a nameExtractor:

CxNavigatorObserver(
nameExtractor: (route) => route.settings.name ?? route.runtimeType.toString(),
);

Set labels​

Sets the labels for the Coralogix exporter.

final labels = {'stock': 'NVDA', 'price': 104};
await CxFlutterPlugin.setLabels(labels);

Set user context​

Setting User Context

var userContext = UserMetadata(
userId: '456',
userName: 'Robert Davis',
userEmail: 'robert.davis@example.com',
userMetadata: {'car': 'tesla'},
accountId: 'acc-42', // optional, from 0.16.0
accountName: 'Acme Corp', // optional, from 0.16.0
);

await CxFlutterPlugin.setUserContext(userContext);

New session​

Force-start a fresh RUM session on demand — typically on user logout — without a full re-init. A new session id is issued and per-session state resets, exactly like the SDK's automatic idle / max-age rotation.

await CxFlutterPlugin.createNewSession();

Shutdown​

Shuts down the Coralogix exporter and marks it as uninitialized.

await CxFlutterPlugin.shutdown();
Last updated on
Was this page helpful?