Symbolication guide

Stacktraces from Apple platforms include backtraces with memory addresses, but symbolication is required to replace the memory addresses with human-readable function names, file paths, and line numbers. Bugsnag supports symbolicating crash reports using the contents of your debug symbol (dSYM) files, which are generated by compiling your app.

With Bitcode

If you have Bitcode enabled in your application’s project settings, the dSYM files available on your Mac will not contain the information needed to symbolicate crash reports. Instead, dSYM files are generated by the App Store when your app is recompiled after upload and will need to be downloaded using Xcode or iTunes Connect or with tools like Fastlane.

Using Fastlane

Fastlane is a suite of tools for automating mobile development tasks. It handles authentication with iTunes Connect to ease downloading dSYM files. Bugsnag provides an action to upload debugging symbols using a plugin.

To install the plugin, run fastlane add_plugin bugsnag. Next, create a lane in your Fastfile to download your dSYM files and upload them to Bugsnag:

lane :refresh_dsyms do
  download_dsyms(version: "1.4.2.1")     # Download dSYM files from iTC
  upload_symbols_to_bugsnag              # Upload them to Bugsnag
  clean_build_artifacts                  # Delete the local dSYM files
end

Once your lane is configured, run your lane to download and upload your dSYM files:

$ fastlane refresh_dsyms

If your dSYM files are not yet available for your app version, retry later once your app has been recompiled by the App Store.

For more information downloading dSYMs using Fastlane as well as available options, see the download_dsyms Fastlane action documentation or the Fastlane getting started guide for iOS.

Using manual downloads

To get started, download the dSYM ZIP archive using Xcode or iTunes Connect. It may take time for the download to become available, as the App Store needs to recompile the your app. Once downloaded, the file can be uploaded to Bugsnag using bugsnag-upload, a script for validating and uploading your dSYM files. Bugsnag-upload is available for download using Homebrew or by downloading the source.

$ bugsnag-dsym-upload YOUR-dSYM-FILES.zip

For more information on the Bitcode recompilation process and downloading dSYMs, see the Apple developer documentation on understanding crash reports.

Without Bitcode

After completing each app build, the dSYM files are available on your local machine and ready to be uploaded to Bugsnag. This process can be automated by adding a build phase to your project which uploads any generated dSYM files to Bugsnag after each build.

With Fastlane

Fastlane is a suite of tools for automating mobile development tasks. Bugsnag provides an action to upload debugging symbols using a plugin.

To install the plugin, run fastlane add_plugin bugsnag. Next, create a lane in your Fastfile to upload symbols to Bugsnag:

lane :upload_dsyms do
  upload_symbols_to_bugsnag # Upload them to Bugsnag
end

Then run your lane to download and upload your dSYM files:

$ fastlane upload_dsyms

Alternately, if you use Fastlane to build and release your application, add the upload_symbols_to_bugsnag action to end of your build and release lane:

lane :release do
  # ... (prior build steps)
  upload_symbols_to_bugsnag
end

Using CocoaPods plugin

If you are using CocoaPods, installing the cocoapods-bugsnag plugin will add a build phase to upload dSYM files when you run pod install. To install, run gem install cocoapods-bugsnag.

Once added, uploading your dSYM files to Bugsnag will occur automatically.

Adding a build phase manually

If using neither Fastlane, nor the CocoaPods plugin, adding a build phase to your project can be configured manually.

  1. From the “Build Phases” screen, click the plus in the bottom right of the screen labelled “Add Build Phase”, then select “Add Run Script”
  2. Expand the newly added “Run Script” section, and set the shell to /usr/bin/ruby
  3. Copy the following script into the text box:
fork do
  Process.setsid
  STDIN.reopen("/dev/null")
  STDOUT.reopen("/dev/null", "a")
  STDERR.reopen("/dev/null", "a")

  require 'shellwords'

  Dir["#{ENV["DWARF_DSYM_FOLDER_PATH"]}/*/Contents/Resources/DWARF/*"].each do |dsym|
    system("curl -F dsym=@#{Shellwords.escape(dsym)} -F projectRoot=#{Shellwords.escape(ENV["PROJECT_DIR"])} https://upload.bugsnag.com/")
  end
end

Once added, uploading your dSYM files to Bugsnag will occur automatically.

Troubleshooting missing dSYM files

When Bugsnag receives an error and dSYM files are not available to symbolicate the error, the error’s stacktrace displays raw memory addresses. Finding and uploading the missing files automatically triggers symbolication of recorded errors in Bugsnag, revealing human-readable function names, file paths, and line numbers in place of memory addresses.

Following the guide above for configuring dSYM file uploads should resolve issues in future builds, however the following steps should help with troubleshooting issues with missing dSYM files in existing app builds with errors in Bugsnag.

Troubleshooting for Bitcode-enabled apps

If Bitcode is enabled in your application settings, your dSYM files are generated by the App Store when your app is recompiled after upload. It is possible that your dSYM files are not yet available as recompilation has not completed, or that errors or failure occurred while the files were being uploaded. To fix, configure or retry the steps for uploading dSYM files for Bitcode-enabled apps above.

Contact support if you have questions or further issues persist after dSYM file upload has been successfully configured.

Troubleshooting for apps without Bitcode

When not using Bitcode, the dSYM files for a particular build of an app are available on the machine where it was compiled. Resolving this issue requires finding and uploading those files.

  1. A list of missing dSYM files is available within a Bugsnag project’s settings on a page named “Missing dSYMs”. The missing files can be located using mdfind and the UUIDs listed in the table on that page.

    $ mdfind YOUR_UUID_HERE
    
  2. Once a required dSYM file has been located, use bugsnag-upload to upload all dSYM files in the same directory. Bugsnag-upload is available for download using Homebrew or by downloading the source.

    $ mdfind YOUR_UUID_HERE
    path/to/dsyms/MyApp.dSYM
    $ bugsnag-dsym-upload path/to/dsyms
    

Completing these steps for all missing dSYM files should resolve the issue, however if issues persist or you have further questions, please contact support.

Troubleshooting hidden symbols

If you have enabled bitcode and opted not to send the app symbols to Apple, the dSYMs uploaded to Bugsnag will not contain the original symbols so the file and class will be displayed as hidden, for example __hidden#231_.

This can be fixed by combining the dSYMs downloaded from Apple with symbol maps that were generated at build time.

If you are using Fastlane, set the symbol_maps_path parameter to the directory containing the symbol maps:

upload_symbols_to_bugsnag(symbol_maps_path: "path/to/BCSymbolMaps")

If you are using bugsnag-dsym-upload set the --symbol-map argument to the directory containing the symbol maps:

$ bugsnag-dsym-upload --symbol-map path/to/BCSymbolMaps dSYMs.zip

The symbol maps can be found in the BCSymbolMaps directory of your archive, for example:

~/Library/Developer/Xcode/Archives/2017-01-01/example-app.xcarchive/BCSymbolMaps