--- 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: `pubspec.yaml` ```yaml dev_dependencies: sentry_dart_plugin: ^3.3.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 `pubspec.yaml` ```yaml sentry: 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 # 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 ``` 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. ## [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. ```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 ``` ## [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 ``` ## [Android ProGuard Integration](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/dart-plugin.md#android-proguard-integration) Uploading ProGuard mapping files is recommended in order to see symbolicated stack traces for errors that occur in the native Android layer: * **Use the Sentry Android Gradle Plugin (Recommended).** After installing the [Sentry Android Gradle Plugin](https://docs.sentry.io/platforms/android/configuration/gradle.md), set `autoInstallation` to `false` in your `app/build.gradle` file: `app/build.gradle` ```groovy sentry { autoInstallation { enabled = false } } ``` This avoids conflicts because Sentry Flutter already ships with a compatible Sentry Android SDK. Follow the [Android Gradle Plugin guide](https://docs.sentry.io/platforms/android/configuration/gradle.md#proguardr8--dexguard) to complete the ProGuard mapping setup. * **Use the Sentry CLI.** Alternatively, you can use the [Sentry CLI](https://docs.sentry.io/cli/dif.md#uploading-files) to manually upload mapping files. Sentry's Flutter SDK doesn't currently support the `uploadNativeSymbols` flag from the Sentry Gradle 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: `pubspec.yaml` ```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: `pubspec.yaml` ```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; }; ```