feat(flutter): add troubleshooting docs (#14529)

Add some troubleshooting docs

---------

Co-authored-by: Alex Krawiec <[email protected]>

Author: buenaflor

docs/platforms/dart/guides/flutter/troubleshooting.mdx

@@ -6,6 +6,60 @@ 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 pinpoint where the problem originated 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 give you the complete picture.
+
+### Example of the Problem
+
+Here's a simple example that demonstrates this issue:
+
+```dart
+Future<void> 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<void> 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).
+
+### 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/) 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 +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 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. 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:
@@ -77,6 +131,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 (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).
+
+If you run into problems, make sure you have a JDK installed on your computer. We recommend using version 17.
+
+<Alert level="info">
+
+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.
+
+</Alert>
 
 ### `SentryFlutter.init` Throws a `sentry_init failed` Error