From 29325d6dc80a5f9e4ebaacf55127345738569cde Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Mon, 2 Feb 2026 12:16:08 +0100 Subject: [PATCH 01/10] Update --- .../flutter/debug-symbols/dart-plugin.mdx | 5 +- .../dart-plugin/dart.flutter.mdx | 239 ++++++++++++++---- 2 files changed, 190 insertions(+), 54 deletions(-) diff --git a/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx b/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx index 2022554c1e9cd..cc1f067744da2 100644 --- a/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx +++ b/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx @@ -4,6 +4,9 @@ description: "Learn how to use the Sentry Dart Plugin to automatically upload de sidebar_order: 1 --- -The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Flutter applications. It automates the upload process for Android, iOS, macOS, and Web, making it seamless to provide Sentry with the necessary files for symbolication. +The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Flutter applications. It uploads debug symbols and source maps to Sentry which enables: +- **Readable stack traces** - See actual function names instead of obfuscated code +- **Source context** - View the exact lines of code that caused the error +- **Readable issue titles** - Obfuscated issue titles are now readable \ No newline at end of file diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index 8464a8b484154..562c2cdcec98b 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -1,3 +1,5 @@ +For a detailed list of features see the [Features](#features) section. + ## Installation In your `pubspec.yaml`, add `sentry_dart_plugin` as a new dev dependency: @@ -13,9 +15,9 @@ The Sentry Dart Plugin requires basic configuration in your `pubspec.yaml` file: @@ -28,6 +30,7 @@ sentry: # Used to make obfuscated Flutter issue titles readable on iOS and Android # See the "Building Your Application" section below for more details on how to generate the symbol map file # Available since version 3.2.0 of the Sentry Dart Plugin + # Only applicable for obfuscated builds dart_symbol_map_path: build/app/obfuscation.map.json # ___PRODUCT_OPTION_START___ source-context # Enable source context @@ -39,36 +42,74 @@ sentry: # ___PRODUCT_OPTION_END___ source-maps ``` +```properties {filename:sentry.properties} +project=___PROJECT_SLUG___ +org=___ORG_SLUG___ +auth_token=___ORG_AUTH_TOKEN___ +# Absolute or relative path to the Dart symbol map file +# Used to make obfuscated Flutter issue titles readable on iOS and Android +# See the "Building Your Application" section below for more details on how to generate the symbol map file +# Available since version 3.2.0 of the Sentry Dart Plugin +dart_symbol_map_path=build/app/obfuscation.map.json +# ___PRODUCT_OPTION_START___ source-context +# Enable source context +upload_sources=true +# ___PRODUCT_OPTION_END___ source-context +# ___PRODUCT_OPTION_START___ source-maps +# Enable source maps (only relevant for Flutter Web) +upload_source_maps=true +# ___PRODUCT_OPTION_END___ source-maps +``` + For iOS and Android builds, source context is only supported if you build the Flutter app using the `--split-debug-info` flag. Additionally source context currently only covers code in the main app package. For example, if your main app package depends on an internal package or a third-party package and an error occurs in that dependency, its source context will not be shown. - - - -The `upload_debug_symbols` option defaults to `true` when not specified. + ### Alternative Configuration Methods -In addition to configuring the plugin in `pubspec.yaml`, you can use: -- Environment variables -- Properties file +You can also define the configuration via command-line arguments or a separate properties file. + +**Environment variables**: + +```bash +export SENTRY_RELEASE=my-app@1.0.0 +``` + +**Command-line arguments**: configure value using `--sentry-define`: + +```bash +dart run sentry_dart_plugin --sentry-define=release=my-app@1.0.0 +``` + +Order of precedence is: +1. Environment variables (highest priority) +2. Command-line arguments +3. pubspec.yaml +4. sentry.properties -For more information, read the [Sentry Dart Plugin README](https://github.com/getsentry/sentry-dart-plugin/tree/main?tab=readme-ov-file#configuration-optional). +The final configuration is the result of merging all the configuration sources together and the value with the highest priority wins. + +For the full list of configuration options see the [Configuration Reference](#configuration-reference) section. ## Building Your Application -Before running the plugin, build your Flutter application with one of the following commands. Obfuscated is encouraged for production builds, and will make uploading debug symbols necessary to get readable stack traces. +Before running the plugin, build your Flutter application. Obfuscation is encouraged for production builds, and will make uploading debug symbols necessary to get readable stack traces. -The `--extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json` option is required to generate the symbol map file which is used to make the obfuscated Flutter issue titles readable on iOS and Android. -Make sure to set the `dart_symbol_map_path` option in your `pubspec.yaml` file to the path of the `obfuscation.map.json` file. + The + `--extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json` + option is required to generate the symbol map file which is used to make the + obfuscated Flutter issue titles readable on iOS and Android. Make sure to set + the `dart_symbol_map_path` option in your `pubspec.yaml` file to the path of + the `obfuscation.map.json` file. -```bash {tabTitle: Obfuscated} +```bash {tabTitle: Mobile & Desktop} flutter build apk --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json flutter build ios --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json flutter build macos --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json @@ -76,12 +117,9 @@ flutter build windows --obfuscate --split-debug-info= --extra- flutter build linux --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json ``` -```bash {tabTitle: Flutter Web} +```bash {tabTitle: Web} flutter build web --release --source-maps ``` - -For Flutter web run `flutter build web --release --source-maps` to generate source maps. - ## Running the Plugin @@ -91,12 +129,6 @@ After building your application, run the plugin to upload debug symbols: flutter pub run sentry_dart_plugin ``` - - -If you don't obfuscate your build, the plugin won't upload debug symbols. Additionally, source context (viewing source code in stack trace frames on Sentry) is not currently supported for non-obfuscated builds. GitHub Issue: [sentry-dart/#1314](https://github.com/getsentry/sentry-dart/issues/1314) - - - ## Android ProGuard Integration If you have ProGuard (`minifyEnabled`) enabled and you want to see proper native Android stacktraces, you must upload Android Proguard/R8 mapping files. You have two options: @@ -127,36 +159,137 @@ Sentry's Flutter SDK doesn't currently support the `uploadNativeSymbols` flag fr +## Features + +The Sentry Dart Plugin uploads debug symbols and source maps to make your Flutter errors readable. Here's what you get on each platform: + +### Dart Code + +#### Mobile & Desktop — Non-Obfuscated Builds + +| Feature | iOS | Android | macOS | Windows | Linux | +| -------------------- | --- | ------- | ----- | ------- | ----- | +| Readable Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ | +| Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* | +| Readable Issue Title | ✓ | ✓ | ✓ | ✓ | ✓ | + +\*Requires `--split-debug-info` build flag supplied to the `flutter build` command + +#### Mobile & Desktop — Obfuscated Builds (`--obfuscate`) + +| Feature | iOS | Android | macOS | Windows | Linux | +| -------------------- | ------- | ------- | ------------- | ------------- | ------------- | +| Readable Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ | +| Source Context | ✓\*\* | ✓\*\* | ✓\*\* | ✓\*\* | ✓\*\* | +| Readable Issue Title | ✓ | ✓ | Not Supported | Not Supported | Not Supported | + +\*Requires `--split-debug-info` build flag supplied to the `flutter build` command + +#### Web (Always Minified) + +| Feature | Support | +| -------------------- | ------------- | +| Readable Stacktrace | ✓ | +| Source Context | ✓ | +| Readable Issue Title | Not Supported | + ## Configuration Reference -The following table lists all available configuration options for the Sentry Dart Plugin: - -
- -| Option | Type | Default | Description | Environment Variable | -|--------|------|---------|-------------|---------------------| -| `project` | string | | **Required.** Your project's name (e.g., `sentry-flutter`) | `SENTRY_PROJECT` | -| `org` | string | | **Required.** Your organization's slug (e.g., `sentry-sdks`) | `SENTRY_ORG` | -| `auth_token` | string | | **Required.** The Sentry auth token | `SENTRY_AUTH_TOKEN` | -| `upload_debug_symbols` | boolean | `true` | Enables or disables automatic upload of debug symbols | | -| `upload_source_maps` | boolean | `false` | Enables or disables automatic upload of source maps | | -| `upload_sources` | boolean | `false` | Enables or disables source code upload | | -| `dart_symbol_map_path` | string | | Absolute or relative path to the Dart symbol map file used to make obfuscated Flutter issue titles readable on iOS and Android | | -| `url` | string | | The URL of your Sentry instance | `SENTRY_URL` | -| `url_prefix` | URL prefix for JS source maps | e.g. ~/app/ (string) | no | - | -| `wait_for_processing` | boolean | `false` | Whether to wait for server-side processing of uploaded files | | -| `log_level` | string | `warn` | Configures the log level for sentry-cli (`trace`, `debug`, `info`, `warn`, `error`) | `SENTRY_LOG_LEVEL` | -| `release` | string | `name@version` from pubspec | The release version for source maps | `SENTRY_RELEASE` | -| `dist` | string | | Custom distribution identifier | `SENTRY_DIST` | -| `web_build_path` | string | `build/web` | The web build folder path | | -| `commits` | string | `auto` | Release commits integration | | -| `ignore_missing` | boolean | `false` | Ignore missing commits previously used in the release | | -| `bin_dir` | string | `.dart_tool/pub/bin/sentry_dart_plugin` | The folder where the plugin downloads the sentry-cli binary | | -| `bin_path` | string | | Path to a sentry-cli binary to use instead of downloading | | -| `sentry_cli_cdn_url` | string | `https://downloads.sentry-cdn.com/sentry-cli` | Alternative place to download sentry-cli | `SENTRYCLI_CDNURL` | - -
+The following table lists all available configuration options for the Sentry Dart Plugin. + +The **Key** column applies to the following configuration sources: + +- **pubspec.yaml** +- **sentry.properties** +- **--sentry-define** + +Environment variables (where available) have the highest priority and override all other methods. + +| Key | Env Variable | Type | Default | Description | +| -------------------------- | ------------------- | ------- | --------------------------------------------- | ---------------------------------------------------------------------------------- | +| `project` | `SENTRY_PROJECT` | string | | **(Required)** Your project's name (e.g., `sentry-flutter`) | +| `org` | `SENTRY_ORG` | string | | **(Required)** Your organization's slug (e.g., `sentry-sdks`) | +| `auth_token` | `SENTRY_AUTH_TOKEN` | string | | **(Required)** The Sentry auth token | +| `upload_debug_symbols` | — | boolean | `true` | Enables or disables automatic upload of debug symbols | +| `upload_source_maps` | — | boolean | `false` | Enables or disables automatic upload of source maps (Flutter Web) | +| `upload_sources` | — | boolean | `false` | Enables or disables source code upload | +| `dart_symbol_map_path` | — | string | | Path to the Dart symbol map file for readable obfuscated issue titles | +| `release` | `SENTRY_RELEASE` | string | `name@version` from pubspec | The release version for source maps | +| `dist` | `SENTRY_DIST` | string | Build number (after `+` in version) | Custom distribution identifier | +| `build_path` | — | string | `build` | Base build directory | +| `web_build_path` | — | string | `web` | The web build folder path relative to `build_path` | +| `symbols_path` | — | string | `.` | The directory containing debug symbols. This recursively searches for debug files. | +| `url` | `SENTRY_URL` | string | | The URL of your Sentry instance (for self-hosted) | +| `url_prefix` | — | string | | URL prefix for JS source maps (e.g., `~/`). Required for non-root web deployments | +| `legacy_web_symbolication` | — | boolean | `false` | Uses legacy symbolication for Flutter Web. See [Debug IDs](#debug-ids-flutter-web) | +| `commits` | — | string | `auto` | Release commits integration | +| `ignore_missing` | — | boolean | `false` | Ignore missing commits previously used in the release | +| `wait_for_processing` | — | boolean | `false` | Whether to wait for server-side processing of uploaded files | +| `log_level` | `SENTRY_LOG_LEVEL` | string | `warn` | Log level for sentry-cli: `trace`, `debug`, `info`, `warn`, `error` | +| `bin_dir` | — | string | `.dart_tool/pub/bin/sentry_dart_plugin` | Folder where the plugin downloads the sentry-cli binary | +| `bin_path` | — | string | | Path to a sentry-cli binary to use instead of downloading | +| `sentry_cli_cdn_url` | `SENTRYCLI_CDNURL` | string | `https://downloads.sentry-cdn.com/sentry-cli` | Alternative place to download sentry-cli | +| `sentry_cli_version` | — | string | | Override the sentry-cli version to download | ## Troubleshooting -If you encounter any issues with the Sentry Dart Plugin, refer to [Troubleshooting - Sentry Dart Plugin](/platforms/dart/guides/flutter/troubleshooting#sentry-dart-plugin) for solutions to common problems. +### Missing Release in Git History + +**Problem:** The plugin fails because a previous release cannot be found in the git history. + +**Solution:** Set `ignore_missing: true` in your configuration to bypass this validation: + +```yaml {filename:pubspec.yaml} +sentry: + ignore_missing: true +``` + +### Debug IDs Not Working For Older SDK Versions (Flutter Web) + +**Problem:** Symbolication isn't working for Flutter Web with plugin version 3.0.0+. + +**Solution:** Debug IDs require Sentry Flutter SDK version 9.1.0 or higher. Either: + +1. Upgrade your Sentry Flutter SDK to 9.1.0+, or +2. Set `legacy_web_symbolication: true` to use the legacy symbolication method: + +```yaml {filename:pubspec.yaml} +sentry: + legacy_web_symbolication: true +``` + +### URL Prefix (Flutter Web) + +**Problem:** Source maps aren't matching for a Flutter Web app that's not deployed at the root URL (e.g., `https://example.com/my-app/` instead of `https://example.com/`). + +**Solution:** You need to configure both the `url_prefix` in the plugin and update your stack frame paths in the SDK to match. + +**Step 1:** Add the `url_prefix` to your plugin configuration: + +```yaml {filename:pubspec.yaml} +sentry: + upload_source_maps: true + url_prefix: ~/my-app/ +``` + +**Step 2:** Update the stack frame paths using `beforeSend` so they include the same prefix. This allows Sentry to match the source maps correctly: + +```dart +options.beforeSend = (event, hint) { + for (final exception in event.exceptions ?? []) { + final stackTrace = exception.stackTrace; + if (stackTrace != null) { + for (final frame in stackTrace.frames) { + // Replace with your actual domain and path prefix + const baseUrl = 'https://example.com/'; + final modifiedAbsPath = frame.absPath?.replaceFirst( + baseUrl, + '${baseUrl}my-app/', + ); + frame.absPath = modifiedAbsPath; + } + } + } + return event; +}; +``` From 0bbec252142dc63bc8f55037c268fe13eae5a5fc Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 5 Feb 2026 15:28:31 +0100 Subject: [PATCH 02/10] Update debug symbols page --- .../dart-plugin/dart.flutter.mdx | 154 +++++++++--------- 1 file changed, 75 insertions(+), 79 deletions(-) diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index 562c2cdcec98b..2d5a30960dd72 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -43,6 +43,7 @@ sentry: ``` ```properties {filename:sentry.properties} +# Add this sentry.properties file to your Flutter project root. project=___PROJECT_SLUG___ org=___ORG_SLUG___ auth_token=___ORG_AUTH_TOKEN___ @@ -72,29 +73,28 @@ Additionally source context currently only covers code in the main app package. ### Alternative Configuration Methods -You can also define the configuration via command-line arguments or a separate properties file. +You can also set configuration values with environment variables or `--sentry-define`. -**Environment variables**: +**Environment variables:** ```bash export SENTRY_RELEASE=my-app@1.0.0 ``` -**Command-line arguments**: configure value using `--sentry-define`: +**Command-line arguments (`--sentry-define`):** ```bash dart run sentry_dart_plugin --sentry-define=release=my-app@1.0.0 ``` -Order of precedence is: -1. Environment variables (highest priority) -2. Command-line arguments -3. pubspec.yaml -4. sentry.properties +When the same value is set in multiple places, the highest priority wins: -The final configuration is the result of merging all the configuration sources together and the value with the highest priority wins. +- Environment variables +- `--sentry-define` command-line arguments +- `pubspec.yaml` +- `sentry.properties` -For the full list of configuration options see the [Configuration Reference](#configuration-reference) section. +For the full list of configuration options, see the [Configuration Reference](#configuration-reference) section. ## Building Your Application @@ -131,27 +131,27 @@ flutter pub run sentry_dart_plugin ## Android ProGuard Integration -If you have ProGuard (`minifyEnabled`) enabled and you want to see proper native Android stacktraces, you must upload Android Proguard/R8 mapping files. You have two options: +Uploading ProGuard mapping files is recommended in order to see symbolicated stack traces for errors that occur in the native Android layer: -1. **Use the Sentry Android Gradle Plugin (Recommended)** +- **Use the Sentry Android Gradle Plugin (Recommended).** - After installing the [Sentry Android Gradle Plugin](/platforms/android/configuration/gradle/), set `autoInstallation` to `false` in your `app/build.gradle` file: + After installing the [Sentry Android Gradle Plugin](/platforms/android/configuration/gradle/), set `autoInstallation` to `false` in your `app/build.gradle` file: - ```groovy {filename: app/build.gradle} - sentry { - autoInstallation { - enabled = false - } - } - ``` + ```groovy {filename: app/build.gradle} + sentry { + autoInstallation { + enabled = false + } + } + ``` - This is necessary because Sentry Flutter already ships with a compatible Sentry Android SDK, so we need to avoid conflicts. + This avoids conflicts because Sentry Flutter already ships with a compatible Sentry Android SDK. - Follow the [Android Gradle Plugin guide](/platforms/android/configuration/gradle/#proguardr8--dexguard) to complete the ProGuard mapping setup. + Follow the [Android Gradle Plugin guide](/platforms/android/configuration/gradle/#proguardr8--dexguard) to complete the ProGuard mapping setup. -2. **Use the Sentry CLI** +- **Use the Sentry CLI.** - Alternatively, you can use the [Sentry CLI](/cli/dif/#uploading-files) to manually upload mapping files. + Alternatively, you can use the [Sentry CLI](/cli/dif/#uploading-files) to manually upload mapping files. @@ -159,53 +159,19 @@ Sentry's Flutter SDK doesn't currently support the `uploadNativeSymbols` flag fr -## Features - -The Sentry Dart Plugin uploads debug symbols and source maps to make your Flutter errors readable. Here's what you get on each platform: - -### Dart Code - -#### Mobile & Desktop — Non-Obfuscated Builds - -| Feature | iOS | Android | macOS | Windows | Linux | -| -------------------- | --- | ------- | ----- | ------- | ----- | -| Readable Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ | -| Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* | -| Readable Issue Title | ✓ | ✓ | ✓ | ✓ | ✓ | - -\*Requires `--split-debug-info` build flag supplied to the `flutter build` command - -#### Mobile & Desktop — Obfuscated Builds (`--obfuscate`) - -| Feature | iOS | Android | macOS | Windows | Linux | -| -------------------- | ------- | ------- | ------------- | ------------- | ------------- | -| Readable Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ | -| Source Context | ✓\*\* | ✓\*\* | ✓\*\* | ✓\*\* | ✓\*\* | -| Readable Issue Title | ✓ | ✓ | Not Supported | Not Supported | Not Supported | - -\*Requires `--split-debug-info` build flag supplied to the `flutter build` command - -#### Web (Always Minified) - -| Feature | Support | -| -------------------- | ------------- | -| Readable Stacktrace | ✓ | -| Source Context | ✓ | -| Readable Issue Title | Not Supported | - ## Configuration Reference The following table lists all available configuration options for the Sentry Dart Plugin. -The **Key** column applies to the following configuration sources: +The **Key** column refers to the option name used in: -- **pubspec.yaml** -- **sentry.properties** -- **--sentry-define** +- `pubspec.yaml` +- `sentry.properties` +- `--sentry-define` -Environment variables (where available) have the highest priority and override all other methods. +Environment variables use different names and are listed in the **Environment Variable** column. -| Key | Env Variable | Type | Default | Description | +| Key | Environment Variable | Type | Default | Description | | -------------------------- | ------------------- | ------- | --------------------------------------------- | ---------------------------------------------------------------------------------- | | `project` | `SENTRY_PROJECT` | string | | **(Required)** Your project's name (e.g., `sentry-flutter`) | | `org` | `SENTRY_ORG` | string | | **(Required)** Your organization's slug (e.g., `sentry-sdks`) | @@ -231,38 +197,66 @@ Environment variables (where available) have the highest priority and override a | `sentry_cli_cdn_url` | `SENTRYCLI_CDNURL` | string | `https://downloads.sentry-cdn.com/sentry-cli` | Alternative place to download sentry-cli | | `sentry_cli_version` | — | string | | Override the sentry-cli version to download | +## Features + +The Sentry Dart Plugin uploads debug symbols and source maps to make your Flutter errors readable. Here's what you get on each platform: + +### Mobile & Desktop — Non-Obfuscated Builds + +| Feature | iOS | Android | macOS | Windows | Linux | +| -------------------- | --- | ------- | ----- | ------- | ----- | +| Symbolicated Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ | +| Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* | +| Symbolicated Issue Title | ✓ | ✓ | ✓ | ✓ | ✓ | + +### Mobile & Desktop — Obfuscated Builds (`--obfuscate`) + +| Feature | iOS | Android | macOS | Windows | Linux | +| -------------------- | ------- | ------- | ------------- | ------------- | ------------- | +| Symbolicated Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ | +| Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* | +| Symbolicated Issue Title | ✓ | ✓ | Not Supported | Not Supported | Not Supported | + +\*Requires `--split-debug-info` build flag supplied to the `flutter build` command + +### Web (Always Minified) + +| Feature | Support | +| -------------------- | ------------- | +| Symbolicated Stacktrace | ✓ | +| Source Context | ✓ | +| Symbolicated Issue Title | Not Supported | + ## Troubleshooting -### Missing Release in Git History + -**Problem:** The plugin fails because a previous release cannot be found in the git history. +The plugin fails because a previous release cannot be found in the git history. -**Solution:** Set `ignore_missing: true` in your configuration to bypass this validation: +Set `ignore_missing: true` in your configuration to bypass this validation: ```yaml {filename:pubspec.yaml} sentry: ignore_missing: true ``` -### Debug IDs Not Working For Older SDK Versions (Flutter Web) + -**Problem:** Symbolication isn't working for Flutter Web with plugin version 3.0.0+. + -**Solution:** Debug IDs require Sentry Flutter SDK version 9.1.0 or higher. Either: +Source maps aren't working for Flutter Web with plugin version 3.0.0+. -1. Upgrade your Sentry Flutter SDK to 9.1.0+, or -2. Set `legacy_web_symbolication: true` to use the legacy symbolication method: +Upgrade your Sentry Flutter SDK to 9.1.0+. -```yaml {filename:pubspec.yaml} -sentry: - legacy_web_symbolication: true -``` +If you're using a version of the Sentry Flutter SDK earlier than 9.1.0, you can set `legacy_web_symbolication: true` to use the legacy symbolication method. + + -### URL Prefix (Flutter Web) + -**Problem:** Source maps aren't matching for a Flutter Web app that's not deployed at the root URL (e.g., `https://example.com/my-app/` instead of `https://example.com/`). +Source maps aren't matching for a Flutter Web app that's not deployed at the root URL (e.g., `https://example.com/my-app/` instead of `https://example.com/`). -**Solution:** You need to configure both the `url_prefix` in the plugin and update your stack frame paths in the SDK to match. +Configure both the `url_prefix` in the plugin and update your stack frame paths in the SDK to match. **Step 1:** Add the `url_prefix` to your plugin configuration: @@ -293,3 +287,5 @@ options.beforeSend = (event, hint) { return event; }; ``` + + From b6ce0ab8afc4669c08c1a8aee42158d7a389ce4b Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 5 Feb 2026 15:29:52 +0100 Subject: [PATCH 03/10] Update debug symbols page --- platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index 2d5a30960dd72..f4292cd2a3ca6 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -169,7 +169,7 @@ The **Key** column refers to the option name used in: - `sentry.properties` - `--sentry-define` -Environment variables use different names and are listed in the **Environment Variable** column. +When available, environment variable names are listed in the **Environment Variable** column. | Key | Environment Variable | Type | Default | Description | | -------------------------- | ------------------- | ------- | --------------------------------------------- | ---------------------------------------------------------------------------------- | From 4cd1025afdcec51974dff4c04537215f814ff13d Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 5 Feb 2026 15:32:02 +0100 Subject: [PATCH 04/10] Update debug symbols page --- .../debug-symbols/dart-plugin/dart.flutter.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index f4292cd2a3ca6..1f7f03c006fd2 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -15,9 +15,9 @@ The Sentry Dart Plugin requires basic configuration in your `pubspec.yaml` file: From 50dc8d07fd3cea7e99499925c0d9444478c0aafb Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 5 Feb 2026 15:33:54 +0100 Subject: [PATCH 05/10] Update debug symbols page --- .../dart/guides/flutter/debug-symbols/dart-plugin.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx b/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx index cc1f067744da2..7d1d82d89eacf 100644 --- a/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx +++ b/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx @@ -5,8 +5,8 @@ sidebar_order: 1 --- The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Flutter applications. It uploads debug symbols and source maps to Sentry which enables: -- **Readable stack traces** - See actual function names instead of obfuscated code +- **Symbolicated stack traces** - See actual function names instead of obfuscated code - **Source context** - View the exact lines of code that caused the error -- **Readable issue titles** - Obfuscated issue titles are now readable +- **Symbolicated issue titles** \ No newline at end of file From 35885b60e2da90d9eab0dcddd006e109ce0b16f2 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 5 Feb 2026 15:34:48 +0100 Subject: [PATCH 06/10] Update debug symbols page --- .../dart/guides/flutter/debug-symbols/dart-plugin.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx b/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx index 7d1d82d89eacf..886f3563b8e67 100644 --- a/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx +++ b/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx @@ -4,9 +4,9 @@ description: "Learn how to use the Sentry Dart Plugin to automatically upload de sidebar_order: 1 --- -The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Flutter applications. It uploads debug symbols and source maps to Sentry which enables: -- **Symbolicated stack traces** - See actual function names instead of obfuscated code -- **Source context** - View the exact lines of code that caused the error +The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Flutter applications. It uploads debug symbols and source maps to Sentry which supports: +- **Symbolicated stacktraces** - See actual function names instead of obfuscated code +- **Source context** - Stacktraces enhanced with source code around the location of stack frames that caused the error - **Symbolicated issue titles** \ No newline at end of file From c861adbd433958d8c9445369c63343c1e9f268be Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 5 Feb 2026 15:39:06 +0100 Subject: [PATCH 07/10] Update debug symbols page --- .../debug-symbols/dart-plugin/dart.flutter.mdx | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index 1f7f03c006fd2..89a13a5841ced 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -104,17 +104,13 @@ Before running the plugin, build your Flutter application. Obfuscation is encour The `--extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json` option is required to generate the symbol map file which is used to make the - obfuscated Flutter issue titles readable on iOS and Android. Make sure to set - the `dart_symbol_map_path` option in your `pubspec.yaml` file to the path of - the `obfuscation.map.json` file. + obfuscated Flutter issue titles readable on iOS and Android. Make sure to point + the `dart_symbol_map_path` option to the location of the `obfuscation.map.json` file. ```bash {tabTitle: Mobile & Desktop} -flutter build apk --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json -flutter build ios --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json -flutter build macos --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json -flutter build windows --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json -flutter build linux --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json +# Replace with the mobile or desktop platform you're building for: https://docs.flutter.dev/deployment +flutter build --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json ``` ```bash {tabTitle: Web} From 8ba80dab49f3659df01e6a1647549d2eeb72f868 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 5 Feb 2026 15:40:24 +0100 Subject: [PATCH 08/10] Update debug symbols page --- platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index 89a13a5841ced..e8d99869ee20b 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -109,8 +109,8 @@ Before running the plugin, build your Flutter application. Obfuscation is encour ```bash {tabTitle: Mobile & Desktop} -# Replace with the mobile or desktop platform you're building for: https://docs.flutter.dev/deployment -flutter build --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json +# Replace with the mobile or desktop target you're building for: https://docs.flutter.dev/deployment/obfuscate#supported-targets +flutter build --obfuscate --split-debug-info= --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json ``` ```bash {tabTitle: Web} From da64b0a2e9243b1f837dd2598c39f721a47a4e9b Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 6 Feb 2026 11:21:53 +0100 Subject: [PATCH 09/10] Apply suggestion from @coolguyzone Co-authored-by: Alex Krawiec --- .../platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx b/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx index 886f3563b8e67..bf968c62f0d72 100644 --- a/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx +++ b/docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx @@ -4,7 +4,7 @@ description: "Learn how to use the Sentry Dart Plugin to automatically upload de sidebar_order: 1 --- -The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Flutter applications. It uploads debug symbols and source maps to Sentry which supports: +The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Flutter applications. It uploads debug symbols and source maps to Sentry, this enables: - **Symbolicated stacktraces** - See actual function names instead of obfuscated code - **Source context** - Stacktraces enhanced with source code around the location of stack frames that caused the error - **Symbolicated issue titles** From bc0877156762322f85a21acfa5bce34cb0777f17 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 6 Feb 2026 11:22:03 +0100 Subject: [PATCH 10/10] Apply suggestion from @coolguyzone Co-authored-by: Alex Krawiec --- platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx index e8d99869ee20b..b56378a210b36 100644 --- a/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx +++ b/platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx @@ -87,7 +87,7 @@ export SENTRY_RELEASE=my-app@1.0.0 dart run sentry_dart_plugin --sentry-define=release=my-app@1.0.0 ``` -When the same value is set in multiple places, the highest priority wins: +When the same value is set in multiple places, the highest priority wins in this order (highest to lowest): - Environment variables - `--sentry-define` command-line arguments