feat: autocapture unhandled exceptions #214

ioannisj · 2025-10-17T20:07:39Z

💡 Motivation and Context

Part of PostHog/posthog#38845

Base is currently #212. Will rebase once merged

Adds autocapture for Flutter framework and Dart platform unhandled exceptions

💚 How did you test it?

Unit tests: TODO

📝 Checklist

I reviewed the submitted code.
I added tests to verify the changes.
I updated the docs if needed.
No breaking change or entry added to the changelog.

ioannisj · 2025-10-17T20:09:11Z

Still need to address some feedback on #212, so just looking for a general review on the autocapture approach/config for now 🙏

marandaneto · 2025-10-24T09:23:20Z

lib/src/posthog_config.dart

+  /// Enable automatic capture of unhandled exceptions
+  ///
+  /// When enabled, PostHog will automatically capture:
+  /// - Flutter framework errors (FlutterError.onError)
+  /// - Dart runtime errors (PlatformDispatcher.onError)
+  ///
+  /// Default: false
+  var captureUnhandledExceptions = false;


its confusing having this one and the other 2 more granular configs
i'd prefer to keep just the 2 granular ones

marandaneto · 2025-10-24T09:23:57Z

lib/src/posthog_config.dart

+  /// Controls whether `PlatformDispatcher.onError errors` are captured.
+  ///
+  /// Default: true
+  var captureDartErrors = true;


we should call this one something closer to the listener, eg capturePlatformDispatcherErrors and mention its the Dart errors in the comment docs

marandaneto · 2025-10-24T09:24:40Z

lib/src/posthog_config.dart

+  /// Callback function to determine if an exception should be captured
+  ///
+  /// Return true to capture the exception, false to ignore it.
+  /// If null, all exceptions will be captured (default behavior).
+  ///
+  /// Example:
+  /// ```dart
+  /// shouldCaptureException: (error) {
+  ///   // Don't capture test exceptions
+  ///   if (error is TestException) return false;
+  ///   // Don't capture StateError exceptions
+  ///   if (error is StateError) return false;
+  ///   // Capture all other exceptions
+  ///   return true;
+  /// }
+  /// ```
+  bool Function(dynamic error)? shouldCaptureException;


we should implement #155 instead of having another callback for the very same thing

Yeah agreed. This was more off your comment in one of our calls that it would be good idea to check directly on error type before capturing an exception. Will remove

we should still do that, and we can do it via the before send as well, its not a blocker for this PR tho.
if we add this one now, its hard to remove later

marandaneto · 2025-10-24T09:25:22Z

lib/src/posthog_config.dart

+  /// ```
+  bool Function(dynamic error)? shouldCaptureException;
+
+  // We could skip for now, but we will need this on the native layer soon


i'd remove this comment, adding to toMap wont hurt

marandaneto · 2025-10-24T09:26:01Z

lib/src/posthog_config.dart

  /// - All other packages are inApp unless in inAppExcludes
  var inAppByDefault = true;

+  /// Enable automatic capture of unhandled exceptions


we could add one more config here for android autocapture https://github.com/PostHog/posthog-android/blob/3b565baef8b46510ca515a13f211e245edf1b4c6/posthog/src/main/java/com/posthog/errortracking/PostHogErrorTrackingConfig.kt#L16

marandaneto · 2025-10-24T09:28:30Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+import '../posthog_flutter_platform_interface.dart';
+
+/// Handles automatic capture of Flutter and Dart exceptions
+class PostHogErrorTrackingAutoCaptureIntegration {


we could create the Integration interface here and do it similar to android and ios, with the install, uninstall and setup methods

Skipped since this is now just 1 integration, but I agree that the next integration to be added should follow that pattern?

marandaneto · 2025-10-24T09:29:09Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+    );
+
+    if (config.captureUnhandledExceptions) {
+      _instance!.start();


avoid the use of !

marandaneto · 2025-10-24T09:31:31Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+    // Restore original handlers
+    if (_originalFlutterErrorHandler != null) {
+      FlutterError.onError = _originalFlutterErrorHandler;
+      _originalFlutterErrorHandler = null;
+    }
+
+    if (_originalPlatformErrorHandler != null) {
+      PlatformDispatcher.instance.onError = _originalPlatformErrorHandler;
+      _originalPlatformErrorHandler = null;
+    }


we should restore to the default value regardless if they are null or not
https://github.com/PostHog/posthog-android/blob/3b565baef8b46510ca515a13f211e245edf1b4c6/posthog/src/main/java/com/posthog/errortracking/PostHogErrorTrackingAutoCaptureIntegration.kt#L65
otherwise, if _originalPlatformErrorHandler is null, we will never unhook our own handlers

marandaneto · 2025-10-24T09:34:05Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+      _captureException(
+        error: details.exception,
+        stackTrace: details.stack,
+        handled: false,


we can create a posthogexception wrapper similar to android to pass those values
https://github.com/PostHog/posthog-android/blob/main/posthog/src/main/java/com/posthog/internal/errortracking/PostHogThrowable.kt

Yeah, that was the plan from our discussion in #212. Will do

marandaneto · 2025-10-24T09:35:46Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+  }
+
+  void _posthogFlutterErrorHandler(FlutterErrorDetails details) {
+    // don't capture silent errors (could maybe be a config?)


marandaneto · 2025-10-24T09:36:37Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+  void _posthogFlutterErrorHandler(FlutterErrorDetails details) {
+    // don't capture silent errors (could maybe be a config?)
+    if (!details.silent) {
+      _captureException(


a few more details we should capture eg
https://github.com/getsentry/sentry-dart/blob/a69a51fd1695dd93024be80a50ad05dd990b2b82/packages/flutter/lib/src/integrations/flutter_error_integration.dart#L35-L60

marandaneto · 2025-10-24T09:37:43Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+        error: details.exception,
+        stackTrace: details.stack,
+        handled: false,
+        context: details.context?.toString(),


see https://github.com/PostHog/posthog-flutter/pull/214/files#r2459538837
we should not just toString, check how we stringify the metadata, etc

marandaneto · 2025-10-24T09:39:01Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+    // Call the original handler
+    if (_originalFlutterErrorHandler != null) {
+      try {
+        _originalFlutterErrorHandler!(details);
+      } catch (e) {
+        // Pretty sure we should be doing this to avoid infinite loops
+        debugPrint(
+            'PostHog: Error in original FlutterError.onError handler: $e');
+      }
+    } else {
+      // If no original handler, use the default behavior (default is to dump to console)
+      FlutterError.presentError(details);
+    }


this will swallow the error and modify the apps behaviour, we should just call the _originalFlutterErrorHandler and le do it what it should do
we should wrap in try catch calling our own handler if needed

marandaneto · 2025-10-24T09:42:13Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+  /// Platform error handler for Dart runtime errors
+  void _setupPlatformErrorHandler() {
+    // prevent circular calls
+    if (PlatformDispatcher.instance.onError == _posthogPlatformErrorHandler) {


this was added not a long ago so i am not sure this is available from our min version which is now 3.22
if this was added after 3.22, we have 2 options
either increase the min version or do this https://github.com/getsentry/sentry-dart/blob/a69a51fd1695dd93024be80a50ad05dd990b2b82/packages/flutter/lib/src/utils/platform_dispatcher_wrapper.dart#L49
which is figure out at runtime if its available or not and only set the callback if its available at runtime

iirc PlatformDispatcher.instance.onError does not work on flutter web, so it should be a no op
flutter/flutter#100277

the alternative for web and older versions before having PlatformDispatcher.instance.onError is https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html
https://github.com/getsentry/sentry-dart/blob/a69a51fd1695dd93024be80a50ad05dd990b2b82/packages/dart/lib/src/sentry_run_zoned_guarded.dart#L12
i'd avoid using runZonedGuarded if possible and only support the other things going forward

marandaneto · 2025-10-24T09:46:51Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+    // Call the original handler
+    if (_originalPlatformErrorHandler != null) {
+      try {
+        return _originalPlatformErrorHandler!(error, stackTrace);
+      } catch (e) {
+        debugPrint(
+            'PostHog: Error in original PlatformDispatcher.onError handler: $e');
+        return true; // Consider the error handled
+      }
+    }


same as https://github.com/PostHog/posthog-flutter/pull/214/files#r2459547502

marandaneto · 2025-10-24T09:47:20Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+  }
+
+  Future<void> _captureException({
+    required dynamic error,


always use Object or Object? if nullable, check the whole PR about this

marandaneto · 2025-10-24T09:47:56Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+  }) {
+    return _posthog.captureException(
+      error: error,
+      stackTrace: stackTrace ?? StackTrace.current,


do not use StackTrace.current here, you need to figure this out inside of the captureException so you can set syntheetic or not

marandaneto · 2025-10-24T09:48:43Z

lib/src/posthog.dart

@@ -1,5 +1,6 @@
 import 'package:meta/meta.dart';

+import 'exceptions/posthog_error_tracking_autocapture_integration.dart';


lets make the folder called errortracking which is the name of the product, and focus on this name for naming our things instead of just exceptions

marandaneto · 2025-10-24T09:49:01Z

lib/src/posthog.dart

    return _posthog.setup(config);
  }

+  void installFlutterIntegrations(PostHogConfig config) {


should be private

marandaneto · 2025-10-24T09:49:09Z

lib/src/posthog.dart

+    }
+  }
+
+  void uninstallFlutterIntegrations() {


marandaneto · 2025-10-24T09:50:45Z

missing the Isolate autocapture
see https://github.com/getsentry/sentry-dart/blob/a69a51fd1695dd93024be80a50ad05dd990b2b82/packages/dart/lib/src/isolate_error_integration.dart#L8
this is also IO only (not web), so you have to do dynamic imports

marandaneto · 2025-10-24T09:53:50Z

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

+        error: error,
+        stackTrace: stackTrace,
+        handled: false,
+        context: 'Platform error');


this should be the mechanism.type instead of generic, we dont need the context field here
https://github.com/PostHog/posthog-android/blob/3b565baef8b46510ca515a13f211e245edf1b4c6/posthog/src/main/java/com/posthog/internal/errortracking/ThrowableCoercer.kt#L99

ioannisj added 2 commits October 17, 2025 22:58

feat: add autocapture integration

dd88514

chore: update changelog

248ea91

ioannisj requested review from a team, ablaszkiewicz, daibhin, hpouillot and oliverb123 October 17, 2025 20:09

fix: format

cf504fb

marandaneto reviewed Oct 24, 2025

View reviewed changes

lib/src/posthog.dart

return _posthog.setup(config);

}

void installFlutterIntegrations(PostHogConfig config) {

Copy link

Member

marandaneto Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should be private

marandaneto reviewed Oct 24, 2025

View reviewed changes

lib/src/posthog.dart

}

}

void uninstallFlutterIntegrations() {

Copy link

Member

marandaneto Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same

marandaneto reviewed Oct 24, 2025

View reviewed changes

		@@ -1,5 +1,6 @@
		import 'package:meta/meta.dart';

		import 'exceptions/posthog_error_tracking_autocapture_integration.dart';

Uh oh!

feat: autocapture unhandled exceptions #214

Are you sure you want to change the base?

feat: autocapture unhandled exceptions #214

Uh oh!

Conversation

ioannisj commented Oct 17, 2025

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

Uh oh!

ioannisj commented Oct 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marandaneto commented Oct 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants