Sentry Dart Plugin
Learn how to use the Sentry Dart Plugin to automatically upload debug symbols for your Dart application.
The Sentry Dart Plugin is the recommended way to upload debug symbols for Dart applications. It automates the upload process for Android, iOS, macOS, and Web, making it seamless to provide Sentry with the necessary files for symbolication.
In your pubspec.yaml, add sentry_dart_plugin as a new dev dependency:
pubspec.yamldev_dependencies:
sentry_dart_plugin: ^2.4.1
The Sentry Dart Plugin requires basic configuration in your pubspec.yaml file:
sentry: project: ___PROJECT_SLUG___ org: ___ORG_SLUG___ auth_token: sntrys_YOUR_TOKEN_HERE
In addition to configuring the plugin in pubspec.yaml, you can use:
- Environment variables
- Properties file
For more information, read the Sentry Dart Plugin README.
Before running the plugin, build your application with one of the following commands:
flutter build apk
flutter build ios
flutter build macos
Include the --obfuscate flag with the --split-debug-info option:
flutter build apk --obfuscate --split-debug-info=<output-directory>
flutter build ios --obfuscate --split-debug-info=<output-directory>
flutter build macos --obfuscate --split-debug-info=<output-directory>
For Flutter Web, generate source maps:
flutter build web --release --source-maps
After building your application, run the plugin to upload debug symbols:
flutter packages pub run sentry_dart_plugin
If you don't obfuscate your build, the plugin won't upload debug symbols but will still configure source context if enabled.
If you have ProGuard (minifyEnabled) enabled, you must upload Android Proguard/R8 mapping files. You have two options:
Use the Sentry Android Gradle Plugin (Recommended)
After installing the Sentry Android Gradle Plugin, set
autoInstallationtofalsein yourapp/build.gradlefile:app/build.gradleCopiedsentry { autoInstallation { enabled = false } }This is necessary because Sentry Flutter already ships with a compatible Sentry Android SDK, so we need to avoid conflicts.
Follow the Android Gradle Plugin guide to complete the ProGuard mapping setup.
Use the Sentry CLI
Alternatively, you can use the Sentry CLI to manually upload mapping files.
Sentry's Flutter SDK doesn't currently support the uploadNativeSymbols flag from the Sentry Gradle Plugin.
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 | |
url | string | The URL of your Sentry instance | SENTRY_URL | |
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 |
If you encounter any issues with the Sentry Dart Plugin, refer to Troubleshooting - Sentry Dart Plugin for solutions to common problems.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").