Sentry Dart Plugin

The 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 section.

Installation

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

dev_dependencies:
  sentry_dart_plugin: ^3.2.1

Configuration

The Sentry Dart Plugin requires basic configuration in your pubspec.yaml file:

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

Alternative Configuration Methods

You can also set configuration values with environment variables or --sentry-define.

Environment variables:

export SENTRY_RELEASE=my-app@1.0.0

Command-line arguments (--sentry-define):

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 section.

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.

# Replace <target> with the mobile or desktop target you're building for: https://docs.flutter.dev/deployment/obfuscate#supported-targets
flutter build <target> --obfuscate --split-debug-info=<output-directory> --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json

Running the Plugin

After building your application, run the plugin to upload debug symbols:

flutter pub run sentry_dart_plugin

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, set autoInstallation to false in your app/build.gradle file:

  Groovy

  app/build.gradle

  Copied

  sentry {
      autoInstallation {
        enabled = false
      }
  }
  

  This avoids conflicts because Sentry Flutter already ships with a compatible Sentry Android SDK.

  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.

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.

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

Mobile & Desktop — Obfuscated Builds (--obfuscate)

*Requires --split-debug-info build flag supplied to the flutter build command

Web (Always Minified)

Troubleshooting

sentry:
  ignore_missing: true

sentry:
  upload_source_maps: true
  url_prefix: ~/my-app/

options.beforeSend = (event, hint) {
  for (final exception in event.exceptions ?? <SentryException>[]) {
    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;
};