feat: autocapture unhandled exceptions

CHANGELOG.md

@@ -1,5 +1,14 @@
 ## Next
 
+- feat: add autocapture exceptions ([#214](https://github.com/PostHog/posthog-flutter/pull/214))
+  - **Limitations**:
+    - No Flutter web support
+    - No native iOS exception capture
+    - No native C/C++ exception capture on Android (Java/Kotlin only)
+    - No stacktrace demangling for obfuscated builds ([--obfuscate](https://docs.flutter.dev/deployment/obfuscate) and [--split-debug-info](https://docs.flutter.dev/deployment/obfuscate))
+    - No [source code context](/docs/error-tracking/stack-traces)
+    - No background isolate error capture
+
 ## 5.8.0
 
 - feat: surveys GA ([#215](https://github.com/PostHog/posthog-flutter/pull/215))

android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt

@@ -293,6 +293,16 @@ class PosthogFlutterPlugin :
                     }
                 }
 
+                // Configure error tracking autocapture
+                posthogConfig.getIfNotNull<Map<String, Any>>("errorTrackingConfig") { errorConfig ->
+                    errorConfig.getIfNotNull<Boolean>("captureNativeExceptions") {
+                        errorTrackingConfig.autoCapture = it
+                    }
+                    errorConfig.getIfNotNull<List<String>>("inAppIncludes") { includes ->
+                        errorTrackingConfig.inAppIncludes.addAll(includes)
+                    }
+                }
+
                 sdkName = "posthog-flutter"
                 sdkVersion = postHogVersion
             }

example/lib/main.dart

@@ -16,6 +16,13 @@ Future<void> main() async {
   config.sessionReplayConfig.maskAllImages = false;
   config.sessionReplayConfig.throttleDelay = const Duration(milliseconds: 1000);
   config.flushAt = 1;
+
+  // Configure error tracking and exception capture
+  config.errorTrackingConfig.captureFlutterErrors =
+      true; // Capture Flutter framework errors
+  config.errorTrackingConfig.capturePlatformDispatcherErrors =
+      true; // Capture Dart runtime errors
+
   await Posthog().setup(config);
 
   runApp(const MyApp());

lib/src/error_tracking/dart_exception_processor.dart

@@ -1,5 +1,6 @@
 import 'package:stack_trace/stack_trace.dart';
 import 'utils/isolate_utils.dart' as isolate_utils;
+import 'posthog_exception.dart';
 
 class DartExceptionProcessor {
   /// Converts Dart error/exception and stack trace to PostHog exception format
@@ -12,12 +13,23 @@ class DartExceptionProcessor {
     bool inAppByDefault = true,
     StackTrace Function()? stackTraceProvider, //for testing
   }) {
+    // Extract PostHog metadata if error is wrapped in PostHogException
+    var mechanismType = 'generic';
+    var handled = true;
+    var currentError = error;
+
+    if (error is PostHogException) {
+      handled = error.handled;
+      mechanismType = error.mechanism;
+      currentError = error.source;
+    }
+
     StackTrace? effectiveStackTrace = stackTrace;
     bool isGeneratedStackTrace = false;
 
     // If it's an Error, try to use its built-in stackTrace
-    if (error is Error) {
-      effectiveStackTrace ??= error.stackTrace;
+    if (currentError is Error) {
+      effectiveStackTrace ??= currentError.stackTrace;
     }
 
     // If still null or empty, get current stack trace
@@ -41,7 +53,7 @@ class DartExceptionProcessor {
           )
         : <Map<String, dynamic>>[];
 
-    final errorType = _getExceptionType(error);
+    final errorType = _getExceptionType(currentError);
 
     // Mark exception as synthetic if:
     // - runtimeType.toString() returned empty/null (fallback to 'Error' type)
@@ -53,14 +65,14 @@ class DartExceptionProcessor {
     final exceptionData = <String, dynamic>{
       'type': errorType ?? 'Error',
       'mechanism': {
-        'handled': true, // always true for now
+        'handled': handled,
         'synthetic': isSynthetic,
-        'type': 'generic',
+        'type': mechanismType,
       }
     };
 
     // Add exception message, if available
-    final errorMessage = error.toString();
+    final errorMessage = currentError.toString();
     if (errorMessage.isNotEmpty) {
       exceptionData['value'] = errorMessage;
     }

lib/src/error_tracking/isolate_handler_io.dart

@@ -0,0 +1,31 @@
+import 'dart:isolate';
+
+import 'package:meta/meta.dart';
+
+/// Native platform implementation of isolate error handling
+@internal
+class IsolateErrorHandler {
+  RawReceivePort? _isolateErrorPort;
+
+  /// Add error listener to current isolate (should be main isolate)
+  void addErrorListener(Function(Object?) onError) {
+    _isolateErrorPort = RawReceivePort(onError);
+    final isolateErrorPort = _isolateErrorPort;
+    if (isolateErrorPort != null) {
+      Isolate.current.addErrorListener(isolateErrorPort.sendPort);
+    }
+  }
+
+  /// Remove error listener and clean up
+  void removeErrorListener() {
+    final isolateErrorPort = _isolateErrorPort;
+    if (isolateErrorPort != null) {
+      isolateErrorPort.close();
+      Isolate.current.removeErrorListener(isolateErrorPort.sendPort);
+      _isolateErrorPort = null;
+    }
+  }
+
+  /// Get current isolate name
+  String? get isolateDebugName => Isolate.current.debugName;
+}

lib/src/error_tracking/isolate_handler_web.dart

@@ -0,0 +1,16 @@
+/// Web platform stub implementation of isolate error handling
+/// Isolates are not available on web, so this is a no-op implementation
+class IsolateErrorHandler {
+  /// Add error listener to current isolate (no-op on web)
+  void addErrorListener(Function(dynamic) onError) {
+    // No-op: Isolates are not available on web
+  }
+
+  /// Remove error listener and clean up (no-op on web)
+  void removeErrorListener() {
+    // No-op: Isolates are not available on web
+  }
+
+  /// Get current isolate name (always 'main' on web)
+  String? get isolateDebugName => 'main';
+}