Debug Symbols

We offer a range of methods to provide Sentry with debug symbols so that you can see symbolicated stack traces and triage issues faster.

When to Upload

With default settings, complete stack traces are available in your Dart error, out of the box, unless you use split-debug-info and obfuscate. In those cases, you need to upload the debug information files generated by the flutter build, so Sentry can show you proper stack traces.

Errors raised from the native layer in Flutter apps require certain debug information files to be uploaded. For example, an Android app can use proguard for minification and obfuscation. And when using NDK, dwarf debug files need to be uploaded. Flutter Web requires sourcemaps and iOS apps also require dwarf debug information files.

Automatically Upload Debug Symbols

The easiest way to upload debug symbols is to use the Sentry Dart Plugin which will upload them automatically.

Install

In your pubspec.yaml, add sentry_dart_plugin as a new dev dependency.

dev_dependencies:
  sentry_dart_plugin: ^1.0.0

Build

Run

• flutter build apk
• flutter build ios (or macos), or
• flutter build web

before executing the sentry_dart_plugin plugin.

This build step outputs the debug symbols and source maps that the plugin will upload.

Configure

This Sentry Dart Plugin comes with a default configuration.

To modify this configuration, add a sentry: configuration to the end of your pubspec.yaml file:

sentry:
  upload_debug_symbols: true
  upload_source_maps: false
  upload_sources: false
  project: ...
  org: ...
  auth_token: ...
  url: ...
  wait_for_processing: false
  log_level: error
  release: ...
  web_build_path: ...
  commits: auto
  ignore_missing: true

Available Configuration Fields

project

The project's name, for example sentry-flutter. Required. This is a string type. The alternative environmental variable is SENTRY_PROJECT.

org

Your organization's slug, for example sentry-sdks. Required. This is a string type. The alternative environmental variable is SENTRY_ORG.

auth_token

The Sentry auth token, which will look like <64 random characters>. Required. This is a string type. The alternative environmental variable is SENTRY_AUTH_TOKEN.

upload_debug_symbols

Enables or disables the automatic upload of debug symbols. This is a boolean type with default value true.

upload_source_maps

Enables or disables the automatic upload of source maps. This is a boolean type with default value false.

upload_sources

Does or doesn't include the source code of native code. This is a boolean type with default value false.

url

The URL of your project, for example https<area>://mysentry.invalid/. This is a string type. The alternative environmental variable is SENTRY_URL.

wait_for_processing

Wait for server-side processing of uploaded files. This is a boolean type with default value false.

log_level

Configures the log level for sentry-cli. This is a string type with default value warn. The alternative environmental variable is SENTRY_LOG_LEVEL. Possible values are trace, debug, info, warn, and error.

release

The release version for source maps, it should match the release set by the SDK. This is a string type with default value name@version from pubspec. The alternative environmental variable is SENTRY_RELEASE.

web_build_path

The web build folder. This is a string type with default value build/web.

commits

Release commits integration. This is a string type with default value auto.

ignore_missing

Ignore missing commits previously used in the release. This is a boolean type with default value false.

Run

flutter packages pub run sentry_dart_plugin

Troubleshooting

Refer to Troubleshooting - Sentry Dart Plugin to resolve potential issues.

Manually Upload Debug Symbols

Uploading for iOS and macOS

Sentry requires a dSYM upload to symbolicate your crash logs. The symbolication process unscrambles Apple’s crash logs to reveal the function, file names, and line numbers of the crash. Learn how to upload the dSYM files.

If you use the split-debug-info and obfuscate flags, you need to upload the *.dSYM files instead of the *.symbols files generated by the Flutter build. The *.dSYM files are located in the build folder of your project and not the given split-debug-info folder.

Uploading for Android NDK

The Sentry Dart Plugin will also upload NDK symbols if upload_debug_symbols is enabled. Alternatively, see our docs on uploading Debug Information Files manually with the Sentry CLI.

If you are using a version of sentry_flutter earlier than 5.1, native symbolication on Android requires a specific configuration. Refer to Troubleshooting for more information.

Uploading with ProGuard

If you have ProGuard (minifyEnabled) enabled, you must upload the Android Proguard/R8 mapping files to see complete stack traces. You can upload these files by either using our Gradle integration (recommended) or manually by using the Sentry CLI.

Uploading Source Maps for Flutter Web

The Sentry Dart plugin also uploads source maps if upload_source_maps is enabled. Alternatively, you can use the Sentry CLI to upload your source maps for Flutter Web by following the docs on Managing Release Artifacts. This will automatically enable Source Context as well.

Uploading Source Context for Flutter Android, iOS, and macOS

Use the upload_sources option to enable Source Context.

For more information, check out the Native Symbolication on iOS/macOS and Source Context troubleshooting guides.