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, along with a unique build identifier, 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.

The BugSnag CLI can be used to extract this identifier from your symbol files and upload it to the appropriate BugSnag endpoint in one command:

$ bugsnag-cli upload dart --api-key=YOUR_API_KEY app-debug-info/

See the BugSnag CLI guide for installation and a full list of options.

Alternatively, use the following instructions to extract and upload your build identifier and symbol files to BugSnag:

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'

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

If you are using minification tools, such as ProGuard, DexGuard, or R8 to minify and optimize your Android app, this will cause method and class names to become obfuscated which makes debugging harder. Similarly, for applications which use the NDK, native stacktraces from C or C++ code consist of a list of addresses and numeric offsets.

In order for your stacktraces to remain readable in your dashboard, BugSnag requires that you upload you obfuscation mapping file and the symbols from any native code for each release of your app. See our Showing full stacktraces guide for information on how to set this up in your builds.

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.