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:
pubspec.yamlsentry:
project: example-project
org: example-org
auth_token: sntrys_YOUR_TOKEN_HERE
# Disable automatic upload of debug symbols
# upload_debug_symbols: false
# Enable source context
upload_source_context: true
# Enable source maps
upload_source_maps: true
The upload_debug_symbols option defaults to true when not specified.
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 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.
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>
flutter build windows --obfuscate --split-debug-info=<output-directory>
flutter build linux --obfuscate --split-debug-info=<output-directory>
For Flutter web run flutter build web --release --source-maps to generate source maps.
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
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:
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").