--- title: "Sentry Dart Plugin" description: "Learn how to use the Sentry Dart Plugin to automatically upload debug symbols for your Flutter application." url: https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin/ --- # Sentry Dart Plugin | Sentry for Flutter 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** For a detailed list of features see the [Features](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#features) section. ## [Installation](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#installation) In your `pubspec.yaml`, add `sentry_dart_plugin` as a new dev dependency: ```yaml dev_dependencies: sentry_dart_plugin: ^3.4.0 ``` ## [Configuration](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#configuration) The Sentry Dart Plugin requires basic configuration in your `pubspec.yaml` file: \[ ]Source Maps\[ ]Source ContextdSYM ```yaml sentry: project: 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 # Only applicable for obfuscated builds 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 ``` *Other available variations of the above snippet: properties* 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. ### [Alternative Configuration Methods](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#alternative-configuration-methods) You can also set configuration values with environment variables or `--sentry-define`. **Environment variables:** ```bash export SENTRY_RELEASE=my-app@1.0.0 ``` **Command-line arguments (`--sentry-define`):** ```bash 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 in this order (highest to lowest): * Environment variables * `--sentry-define` command-line arguments * `pubspec.yaml` * `sentry.properties` For the full list of configuration options, see the [Configuration Reference](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#configuration-reference) section. ## [Configure the Android Gradle Plugin](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#configure-the-android-gradle-plugin) This step is only required if R8 or ProGuard is enabled for your Android build. Without it, JVM stack traces are already readable and no mapping file upload is required. Using R8 or ProGuard? Configure the Sentry Android Gradle Plugin For Android, the Sentry Android Gradle Plugin uploads the files needed to symbolicate JVM frames. It runs automatically during your Android build, so configure it before building your app. After installing the [Sentry Android Gradle Plugin](https://docs.sentry.io/platforms/android/configuration/gradle.md), configure it in your `app/build.gradle.kts` file: ```kotlin sentry { // Disable auto-installation of the Sentry Android SDK since it's already installed by the Sentry Flutter SDK autoInstallation { enabled.set(false) } // The slug of the Sentry organization to use for uploading ProGuard mappings. org.set("") // The slug of the Sentry project to use for uploading ProGuard mappings. projectName.set("") // The authentication token to use for uploading ProGuard mappings. // WARNING: Do not expose this token in your build.gradle files, but rather set an environment // variable and read it into this property. authToken.set(System.getenv("SENTRY_AUTH_TOKEN")) } ``` ProGuard mapping upload is enabled automatically by the Sentry Android Gradle Plugin. Alternatively, you can use the [Sentry CLI](https://docs.sentry.io/cli/dif.md#proguard-mapping-upload) to manually upload ProGuard mapping files. For more information, see the [Android Gradle Plugin guide](https://docs.sentry.io/platforms/android/configuration/gradle.md). ## [Building Your Application](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#building-your-application) 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 point the `dart_symbol_map_path` option to the location of the `obfuscation.map.json` file. **Mobile & Desktop** ```bash # 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 ``` **Web** ```bash flutter build web --release --source-maps ``` Even if you don't use `split-debug-info` or `obfuscate`, we recommend uploading all available debug files with the Sentry Dart Plugin. The more you upload, the more Sentry can symbolicate out of the box — including native frames (for example, on iOS) that aren't readable otherwise. ## [Running the Plugin](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#running-the-plugin) After building your application, run the plugin to upload debug symbols: ```bash flutter pub run sentry_dart_plugin ``` ## [Configuration Reference](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#configuration-reference) The following table lists all available configuration options for the Sentry Dart Plugin. The **Key** column refers to the option name used in: * `pubspec.yaml` * `sentry.properties` * `--sentry-define` When available, environment variable names are listed in the **Environment Variable** column. | 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`) | | `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](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#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 | ## [Features](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#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](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#mobile--desktop--non-obfuscated-builds) | Feature | iOS | Android | macOS | Windows | Linux | | ------------------------ | --- | ------- | ----- | ------- | ----- | | Symbolicated Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ | | Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* | | Symbolicated Issue Title | ✓ | ✓ | ✓ | ✓ | ✓ | ### [Mobile & Desktop — Obfuscated Builds (`--obfuscate`)](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#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)](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#web-always-minified) | Feature | Support | | ------------------------ | ------------- | | Symbolicated Stacktrace | ✓ | | Source Context | ✓ | | Symbolicated Issue Title | Not Supported | ## [Troubleshooting](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#troubleshooting) Why does the plugin say a release is missing? The plugin fails because a previous release cannot be found in the git history. Set `ignore_missing: true` in your configuration to bypass this validation: ```yaml sentry: ignore_missing: true ``` Why aren't Flutter Web source maps working with older SDKs? Source maps aren't working for Flutter Web with plugin version 3.0.0+. Upgrade your Sentry Flutter SDK to 9.1.0+. 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. Why don't my Flutter Web source maps match when using a URL prefix? 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/`). 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 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; }; ```