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 App Store Connect or with tools like Fastlane.

Using Fastlane

Fastlane is a suite of tools for automating mobile development tasks. It handles authentication with App Store Connect to ease downloading dSYM files.

BugSnag provides an action to upload debugging symbols. See our Fastlane plugin docs for details.

Using manual downloads

To get started, download the dSYM ZIP archive using Xcode or App Store 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-dsym-upload, a script for validating and uploading your dSYM files. bugsnag-dsym-upload is available for download using Homebrew or by downloading the source.

$ bugsnag-dsym-upload --api-key API_KEY YOUR-dSYM-FILES.zip

If you are using BugSnag On-premise, you should supply your BugSnag Upload API endpoint by specifying the following option:

--upload-server "https://upload.example.com"

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. See our Fastlane plugin docs for details.

Using CocoaPods plugin

If you are using CocoaPods, installing the cocoapods-bugsnag plugin will add a Run Script build phase to your project workspace to upload your dSYM files so the BugSnag service can provide you with symbolicated stack traces. To install, run:

gem install cocoapods-bugsnag

Add pod 'Bugsnag', and plugin 'cocoapods-bugsnag' to your Podfile:

pod 'Bugsnag'
plugin 'cocoapods-bugsnag'

Then, install with:

pod install

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 --http1.1 -F apiKey=your-api-key-here -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-dsym-upload to upload all dSYM files in the same directory. bugsnag-dsym-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