Debug Symbols

Learn about uploading debug symbols to enable symbolication of stack traces in your Dart applications.

Debug symbols are essential for understanding stack traces in your Dart application when errors occur. Without debug symbols, stack traces from minified or obfuscated code can be difficult or impossible to interpret.

Debug symbols provide the necessary information to convert program addresses back to function names, source file names, and line numbers. When you build a Dart application, especially with obfuscation or optimization enabled, this information is typically removed from the main application bundle to reduce size.

In Dart applications, debug symbols can include:

  • For Dart code: Symbol files generated when using --split-debug-info and --obfuscate flags
  • For iOS/macOS: dSYM files
  • For Android: Proguard/R8 mapping files and symbols files
  • For Flutter Web: Source maps
  • For Android NDK: ELF DWARF debug files

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

Errors raised from the native layer in Flutter apps also require debug information files:

  • Android apps using proguard for minification and obfuscation need mapping files
  • iOS/macOS apps require dSYM files
  • Android NDK requires DWARF debug files
  • Flutter Web requires source maps

Sentry offers several methods to upload debug symbols for Dart applications:

  1. Sentry Dart Plugin (Recommended) - The easiest way to automatically upload debug symbols for iOS, Android, and Web.

  2. Manual Upload Options:

    • iOS and macOS - Upload dSYM files for symbolication of Apple platform crashes.
    • Android - Upload mapping files manually using the Sentry CLI.
    • Android NDK - Upload ELF DWARF debug files for native code crashes.
    • Web - Upload source maps for Flutter web applications.

Choose the method that best suits your workflow and platform requirements. For most users, the Sentry Dart Plugin provides the simplest solution across all platforms.

Previous
Manual Setup
Next
Sentry Dart Plugin
Was this helpful?
Help improve this content
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").