From 880c4f2dcf532e9996eda6d91e1e390a1f682c83 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 1 Aug 2025 15:25:55 +0200 Subject: [PATCH 01/10] add more troubleshooting --- .../dart/guides/flutter/troubleshooting.mdx | 76 ++++++++++++++++++- 1 file changed, 75 insertions(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index 0b9c2bf1be042..82e851b0f1ecc 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -6,6 +6,61 @@ sidebar_order: 9000 If you need help solving issues with Sentry's Flutter SDK, you can read the edge cases documented here. If you need additional help, you can [ask on GitHub](https://github.com/getsentry/sentry-dart/issues/new/choose). Customers on a paid plan may also contact support. +## Not Enough Stack Frames Captured or the Captured Frames are Unhelpful For Debugging + +### What's the Problem? + +When errors occur in your Flutter app, you might notice that some error reports in Sentry don't show you the complete stack trace that led to the error. This missing information can make it harder to understand where the problem actually started in your code. + +### When This Problem Occurs + +Sentry automatically captures error details and stack traces using Flutter and Dart's built-in error handling such as `FlutterError.onError`. However, sometimes the stack trace information is not available or becomes incomplete, especially when using `async` and `await` in your code. + +When this happens, Sentry does its best to give you *some* debugging information for example by calling `StackTrace.current` if there is none given by the `onError` hook but it might not be the complete picture you need. + +### Example of the Problem + +Here's a simple example that demonstrates this issue: + +```dart +### Example of the Problem + +```dart +Future tryCatch() async { + await foo(); + + try { + throw StateError('try catch'); + } catch (error) { + // This is only an example, you should not do this in your code + FlutterError.reportError(FlutterErrorDetails(exception: error)); + } +} + +Future foo() async { + bar(); +} + +void bar() { + // ... +} +``` + +If you run this code, you'll see that the error that we automatically capture is the following: + +``` +StateError: Bad state: try catch + #0 FlutterError.reportError (package:flutter/src/foundation/assertions.dart:1204:14) + #1 tryCatch (package:sentry_flutter_example/main.dart:769:18) +``` + +As you can see the stack trace is missing the `foo` and `bar` functions. +This happens because Dart's async/await implementation can cause stack trace information to be lost during asynchronous operations. This is a known limitation of the Dart runtime itself, not a Sentry issue. You can learn more about this in [this Dart issue](https://github.com/dart-lang/sdk/issues/46318). + +**To get better debugging information for these cases:** +- Add relevant context to your Sentry events using [custom tags](/platforms/dart/guides/flutter/data-management/tags/) and [breadcrumbs](/platforms/dart/guides/flutter/data-management/breadcrumbs/) for critical paths in your application +- Consider using [Sentry's Structured Logs](/platforms/dart/logs/) feature to capture additional debugging data alongside your errors + ## Support 16 KB Page Sizes on Android Starting with Android 15, AOSP supports devices with a 16 KB page size. If your app uses NDK libraries (directly or via an SDK), you'll need to rebuild it for compatibility with these devices. @@ -21,7 +76,7 @@ Starting May 1, 2024, Apple requires all apps submitted to the App Store to prov ## Known Limitations - If you enable the `split-debug-info` and `obfuscate` features, you must upload [debug symbols](/platforms/dart/guides/flutter/upload-debug/). -- Issue titles might be obfuscated as we rely on the `runtimeType`, but they may not be human-readable. See the [Obfuscate Caveat](https://flutter.dev/docs/deployment/obfuscate#caveat). +- Issue titles might be obfuscated (or minified on web) as we rely on the `runtimeType`, but they may not be human-readable. We are investigating a solution to this which is tracked in [this issue](https://github.com/getsentry/sentry-dart/issues/2805). - Layout related errors are only caught by [FlutterError.onError](https://api.flutter.dev/flutter/foundation/FlutterError/onError.html) in debug mode. In release mode, they are removed by the Flutter framework. See [Flutter build modes](https://flutter.dev/docs/testing/build-modes). - Use [inbound filters](/concepts/data-management/filtering/) to exclude unhandled errors that are caught outside of your application in release builds. The SDK cannot filter these directly due to obfuscated stack traces. - If your app runs on Windows and uses a Flutter version below `3.3.0`, you need to set the version and build number manually, see [this issue on GitHub](https://github.com/flutter/flutter/issues/73652). To do so: @@ -77,6 +132,25 @@ On Linux, compiling your Flutter Desktop app with the crashpad backend can fail - Update your clang to at least version 13, then try again. - If you still encounter errors, please file an issue on our [Sentry Dart GitHub repository](https://github.com/getsentry/sentry-dart/issues/). + +### Java or JNI Errors when compiling on Flutter Desktop + +Since Sentry Flutter SDK version `9.0.0`, we improved how the SDK works on Android by switching from method channels to JNI (Java Native Interface) for certain operations. + +However, there's a current limitation: Flutter automatically compiles the Dart JNI plugin for all platforms (iOS, Android, etc.), even when you're only building for one platform. + +For example on Windows it will compile components such as `dartjni.dll` which requires a JDK to be installed on your system. + +Ideally it is possible to compile only for the chosen target platform to avoid unnecessary work, but this is currently blocked by [this Dart JNI issue](https://github.com/dart-lang/native/issues/1023). + +If you run into problems, make sure you have a JDK (Java Development Kit) installed on your computer. We recommend using version 17. + + + +This does not affect your end users. Since we only use JNI code on Android, users on other platforms do not need Java installed. +The JDK is only necessary as the developer because the Flutter tooling will compile the Dart JNI plugin for all platforms. + + ### `SentryFlutter.init` Throws a `sentry_init failed` Error From 2917cc2c336c914890c5c691fabcafc57bc74798 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 1 Aug 2025 15:28:21 +0200 Subject: [PATCH 02/10] add more troubleshooting --- docs/platforms/dart/guides/flutter/troubleshooting.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index 82e851b0f1ecc..69264711517df 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -22,7 +22,6 @@ When this happens, Sentry does its best to give you *some* debugging information Here's a simple example that demonstrates this issue: -```dart ### Example of the Problem ```dart From 34b253b168bd495c11dc9014c8a1e515202632b9 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 1 Aug 2025 15:29:32 +0200 Subject: [PATCH 03/10] add more troubleshooting --- docs/platforms/dart/guides/flutter/troubleshooting.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index 69264711517df..ead4ec0d315eb 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -22,8 +22,6 @@ When this happens, Sentry does its best to give you *some* debugging information Here's a simple example that demonstrates this issue: -### Example of the Problem - ```dart Future tryCatch() async { await foo(); From a1bc38f928ed7d2ab7b6f2e17a8f39619ad2b04d Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 1 Aug 2025 15:30:14 +0200 Subject: [PATCH 04/10] add more troubleshooting --- docs/platforms/dart/guides/flutter/troubleshooting.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index ead4ec0d315eb..2bc5fbaf0ba98 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -54,7 +54,9 @@ StateError: Bad state: try catch As you can see the stack trace is missing the `foo` and `bar` functions. This happens because Dart's async/await implementation can cause stack trace information to be lost during asynchronous operations. This is a known limitation of the Dart runtime itself, not a Sentry issue. You can learn more about this in [this Dart issue](https://github.com/dart-lang/sdk/issues/46318). -**To get better debugging information for these cases:** +### What Can You Do? + +In order to get better debugging information for these cases you can: - Add relevant context to your Sentry events using [custom tags](/platforms/dart/guides/flutter/data-management/tags/) and [breadcrumbs](/platforms/dart/guides/flutter/data-management/breadcrumbs/) for critical paths in your application - Consider using [Sentry's Structured Logs](/platforms/dart/logs/) feature to capture additional debugging data alongside your errors From 1b576b854f430c83e3e622052db99f48f83cf135 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 30 Oct 2025 09:32:51 +0100 Subject: [PATCH 05/10] Apply suggestion from @coolguyzone Co-authored-by: Alex Krawiec --- docs/platforms/dart/guides/flutter/troubleshooting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index 2bc5fbaf0ba98..01620ff938d14 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -10,7 +10,7 @@ If you need help solving issues with Sentry's Flutter SDK, you can read the edge ### What's the Problem? -When errors occur in your Flutter app, you might notice that some error reports in Sentry don't show you the complete stack trace that led to the error. This missing information can make it harder to understand where the problem actually started in your code. +When errors occur in your Flutter app, you might notice that some error reports in Sentry don't show you the complete stack trace that led to the error. This missing information can make it harder to pinpoint where the problem originated in your code. ### When This Problem Occurs From 44976389e9bea7c73444de15c60ddc8c8d356a43 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 30 Oct 2025 09:34:25 +0100 Subject: [PATCH 06/10] Update docs/platforms/dart/guides/flutter/troubleshooting.mdx Co-authored-by: Alex Krawiec --- docs/platforms/dart/guides/flutter/troubleshooting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index 01620ff938d14..5225d148d7d7a 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -16,7 +16,7 @@ When errors occur in your Flutter app, you might notice that some error reports Sentry automatically captures error details and stack traces using Flutter and Dart's built-in error handling such as `FlutterError.onError`. However, sometimes the stack trace information is not available or becomes incomplete, especially when using `async` and `await` in your code. -When this happens, Sentry does its best to give you *some* debugging information for example by calling `StackTrace.current` if there is none given by the `onError` hook but it might not be the complete picture you need. +When this happens, Sentry does its best to give you *some* debugging information, for example by calling `StackTrace.current` if there is none given by the `onError` hook, but it might not give you the complete picture. ### Example of the Problem From 14f550f12eb2fb57dac6f24ead9c60787bc5dbc2 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 30 Oct 2025 09:34:36 +0100 Subject: [PATCH 07/10] Update docs/platforms/dart/guides/flutter/troubleshooting.mdx Co-authored-by: Alex Krawiec --- docs/platforms/dart/guides/flutter/troubleshooting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index 5225d148d7d7a..050bcbb64da5f 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -58,7 +58,7 @@ This happens because Dart's async/await implementation can cause stack trace inf In order to get better debugging information for these cases you can: - Add relevant context to your Sentry events using [custom tags](/platforms/dart/guides/flutter/data-management/tags/) and [breadcrumbs](/platforms/dart/guides/flutter/data-management/breadcrumbs/) for critical paths in your application -- Consider using [Sentry's Structured Logs](/platforms/dart/logs/) feature to capture additional debugging data alongside your errors +- Consider using [Sentry's Structured Logs](/platforms/dart/logs/) to capture additional debugging data alongside your errors ## Support 16 KB Page Sizes on Android From bf03d9bcdfe0e8a79a7dac3e51d4c1d40a014848 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 30 Oct 2025 09:35:01 +0100 Subject: [PATCH 08/10] Update docs/platforms/dart/guides/flutter/troubleshooting.mdx Co-authored-by: Alex Krawiec --- docs/platforms/dart/guides/flutter/troubleshooting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index 050bcbb64da5f..056f91ce103e0 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -138,7 +138,7 @@ Since Sentry Flutter SDK version `9.0.0`, we improved how the SDK works on Andro However, there's a current limitation: Flutter automatically compiles the Dart JNI plugin for all platforms (iOS, Android, etc.), even when you're only building for one platform. -For example on Windows it will compile components such as `dartjni.dll` which requires a JDK to be installed on your system. +For example on Windows it will compile components such as `dartjni.dll` which requires a JDK (Java Development Kit) to be installed on your system. Ideally it is possible to compile only for the chosen target platform to avoid unnecessary work, but this is currently blocked by [this Dart JNI issue](https://github.com/dart-lang/native/issues/1023). From 0a2ecac89d3f5366ad17af59f63dd4e2398a0db7 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 30 Oct 2025 09:36:06 +0100 Subject: [PATCH 09/10] Update docs/platforms/dart/guides/flutter/troubleshooting.mdx Co-authored-by: Alex Krawiec --- docs/platforms/dart/guides/flutter/troubleshooting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index 056f91ce103e0..009f8105e5ccb 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -142,7 +142,7 @@ For example on Windows it will compile components such as `dartjni.dll` which re Ideally it is possible to compile only for the chosen target platform to avoid unnecessary work, but this is currently blocked by [this Dart JNI issue](https://github.com/dart-lang/native/issues/1023). -If you run into problems, make sure you have a JDK (Java Development Kit) installed on your computer. We recommend using version 17. +If you run into problems, make sure you have a JDK installed on your computer. We recommend using version 17. From 6437279e01dd2a70676d35325e136bed9de34e61 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 31 Oct 2025 14:58:28 +0100 Subject: [PATCH 10/10] Update known limitations section in troubleshooting guide Clarify obfuscation handling for issue titles and provide guidance for iOS and Android. --- docs/platforms/dart/guides/flutter/troubleshooting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/troubleshooting.mdx b/docs/platforms/dart/guides/flutter/troubleshooting.mdx index 1ed5322e7011f..c7fb9d4b96dbf 100644 --- a/docs/platforms/dart/guides/flutter/troubleshooting.mdx +++ b/docs/platforms/dart/guides/flutter/troubleshooting.mdx @@ -75,7 +75,7 @@ Starting May 1, 2024, Apple requires all apps submitted to the App Store to prov ## Known Limitations - If you enable the `split-debug-info` and `obfuscate` features, you must upload [debug symbols](/platforms/dart/guides/flutter/upload-debug/). -- Issue titles might be obfuscated (or minified on web) as we rely on the `runtimeType`, but they may not be human-readable. We are investigating a solution to this which is tracked in [this issue](https://github.com/getsentry/sentry-dart/issues/2805). +- Issue titles might be obfuscated (or minified on web) as we rely on the `runtimeType`, but they may not be human-readable. For iOS and Android, follow the [Sentry Dart Plugin guide](/platforms/dart/guides/flutter/upload-debug/) to set up the obfuscation map which allows us to deobfuscate the issue tile. We’re currently exploring a solution for Web. - Layout related errors are only caught by [FlutterError.onError](https://api.flutter.dev/flutter/foundation/FlutterError/onError.html) in debug mode. In release mode, they are removed by the Flutter framework. See [Flutter build modes](https://flutter.dev/docs/testing/build-modes). - Use [inbound filters](/concepts/data-management/filtering/) to exclude unhandled errors that are caught outside of your application in release builds. The SDK cannot filter these directly due to obfuscated stack traces. - If your app runs on Windows and uses a Flutter version below `3.3.0`, you need to set the version and build number manually, see [this issue on GitHub](https://github.com/flutter/flutter/issues/73652). To do so: