Showing full stacktraces

Stacktraces in Flutter app errors in production may be unreadable. Bugsnag supports demangling these stacktraces.

The way to make these stacktraces readable will depend on the component that produced the error:

  • Flutter / Dart components: Dart symbols files
  • JVM components on Android: ProGuard / DexGuard / R8 mapping files
  • NDK components on Android: NDK symbols files
  • iOS native components: debug symbol files (dSYMs)

Once the appropriate files have been uploaded the stacktraces of subsequent errors will contain methods, line numbers and file paths. We recommend that you follow the steps below to upload all of these files for your Flutter app to ensure that you get the most from your reported stacktraces.

Dart symbol files

If you use --split-debug-info when building your app it will remove the “symbols” from your Flutter app binaries, and store them in separate files. This means your Flutter app will be unable to include line numbers, method, class and file names in the stacktraces it generates.

For example:

flutter build <artifact> --split-debug-info=app-debug-info

This will produce a directory named app-debug-info containing one .symbols file for each architecture and platform you have targeted. Each of these files needs to be uploaded to Bugsnag in order to make the stacktraces readable. These files are unique to a single build, and each time you build your app (with flutter build) you will also need to upload the new .symbols files.

Uploaded Flutter symbols will only be applied to new error events. They will not be applied retroactively to existing error events.

Use the following instructions to upload your app’s symbol files to Bugsnag along with a unique build identifier that we use to select the appropriate file for each reported event.

Android builds

Use the readelf tool to extract the “Build ID” from each generated .symbols file:

$ readelf --notes app-debug-info/app.android-arm64.symbols | grep 'Build ID'

If readelf is not globally installed on your platform, you can find a suitable version (sometimes named llvm-readelf) in your NDK toolchain.

Use the hexadecimal string produced by this command (such as 0a70ca6d63ab03282a01eabf4f5f33e7) for the buildId parameter (along with your Bugsnag API key), in a cURL command to upload your symbol files to Bugsnag:

$ curl --http1.1 https://upload.bugsnag.com/dart-symbol \
    -F symbolFile=@app-debug-info/app.android-arm64.symbols \
    -F apiKey=YOUR_API_KEY_HERE \
    -F buildId=BUILD_IDENTIFIER

This should be repeated for each architecture you are supporting.

iOS builds

The build identifier for iOS is the Mach-O UUID generated for the binary containing your app’s Dart code. This can be extracted using Xcode’s dwarfdump as follows:

$ dwarfdump --uuid build/ios/iphoneos/MyApp.app/Frameworks/App.framework/App

Use the UUID produced by this command (such as 2B9C4665-56F7-38FD-923E-BBC2F219EDA6) for the buildId parameter (along with your Bugsnag API key), in a cURL command to upload your symbol files to Bugsnag:

$ curl --http1.1 https://upload.bugsnag.com/dart-symbol \
    -F symbolFile=@app-debug-info/app.ios-arm64.symbols \
    -F apiKey=YOUR_API_KEY_HERE \
    -F buildId=BUILD_IDENTIFIER

This should be repeated for each architecture you are supporting.

Android mapping and NDK symbol files

When building a Flutter app with Android components, it’s common to use ProGuard, R8, or DexGuard to minify and optimize your app, this will cause Java / Kotlin method and class names to become obfuscated which makes debugging harder.

To ensure the stacktraces of errors from the Android components of your Flutter app are readable, follow our Android Mapping Support guide.

These tools have no effect on your Dart code.

iOS debug symbol files (dSYMs)

For native iOS components, Bugsnag requires iOS symbols files (.dSYMs) in order to include line numbers and method, class and file names into your stacktraces.

To ensure errors coming from the iOS components of your app are have readable stacktraces, follow our iOS Symbolication guide.