Unlock better Flutter error insights with native symbols support

By Sumitra Manga | Posted Jan 14, 2025 | 3 min. (554 words)

We’re excited to announce that native symbols support for Flutter is now live in Raygun Crash Reporting! If you’ve ever struggled with obfuscated stack traces in your Flutter apps, this update will simplify your debugging workflow and give you more actionable insights into app crashes.

What’s in this article

Why native symbols support matters

Flutter’s ability to combine Dart and native code is powerful—but when native crashes occur, obfuscated stack traces can make debugging a nightmare. Native symbols support makes these stack traces readable, providing clear insights for faster debugging. Here’s what this means for your team:

  • Readable crash reports: Decode obfuscated stack traces automatically.
  • Version-specific symbols: Easily match symbol files with app versions.
  • Flexible debugging options: Use Raygun’s Flutter symbols center for automation or decode manually if preferred.

How to enable native symbols

Raygun offers two approaches to handling symbols: automatic and manual. Here’s how they work:

Mobile/native - automatic

If you’re using Flutter’s --obfuscate parameter to obfuscate code during builds, you can decode stack traces with Raygun’s Flutter symbols center. Here’s the process:

  1. Upload symbols to the Flutter symbols center:
    • Navigate to the ‘Application settings’ section of your app in Raygun and select ‘Flutter symbols center’.
    • Add the version number of your symbols and upload the corresponding file/s. If your application supports multiple platforms and architectures, ensure that you upload all the symbols available
  2. Ensure filenames follow the correct convention:
    • app.{platform}-{architecture}.symbols
  3. Set the version in your crash reports:
    • Ensure the version in the uploaded symbols matches the version in your crash reports.
    • During initialization, include the version with Raygun.init() or set it using .setVersion().
  4. Wait for processing: Uploaded symbol files might take up to 30 minutes to process. If you encounter errors during this time or want to process errors that have appeared before uploading the symbols, simply use the ‘Re-process this error for Flutter symbols’ button on the error instance to retry symbolification.

Check out our documentation for detailed steps!

Flutter symbols demo

Mobile/native - manual

Prefer a hands-on approach? Flutter’s SDK includes the flutter symbolize command for manual decoding. Here’s how it works:

  1. Copy the stack trace: Extract the obfuscated stack trace from your crash report into a text file (e.g., stack.txt). It should look something like this:
    at #00 abs 00000070889bcc93 virt 000000000018fc93 _kDartIsolateSnapshotInstructions+0xb9153 (unparsed:null)  
    at #01 abs 00000070889464fb virt 00000000001194fb _kDartIsolateSnapshotInstructions+0x429bb (unparsed:null)  
    ... etc ...
  1. Run the symbolize command: Use the flutter symbolize command with your stack trace and corresponding symbol file.
    flutter symbolize -i stack.txt -d out/android/app.android-arm64.symbols
  1. View the decoded output: The command will output a human-readable stack trace with file and line numbers, like this:
    at #0      _MyAppState.build.<anonymous closure> (/[redacted]/lib/main.dart:89:17)  
    at #1      _InkResponseState.handleTap (//[redacted]/flutter/packages/flutter/lib/src/material/ink_well.dart:1170:21)  
    ... etc ...

Why Raygun + Flutter = debugging bliss

Raygun’s native symbols support takes the guesswork out of debugging Flutter apps. Whether you choose the automatic method for convenience or prefer manual control, the result is the same: fast, clear insights that help you fix crashes quickly.

Ready to try it out? Check out the setup guide and start uploading your symbols today.

As always, we’re here to help—reach out if you have questions or feedback.

Not a Raygun customer? Try out the full Crash Reporting application free for 14 days!