Showing full stacktraces

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.

Uploading dSYM files

After completing each app build, the dSYM files are available on your local machine and ready to be uploaded to BugSnag. The following tools are available to perform this upload during your builds:

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 plugin 'cocoapods-bugsnag' to your Podfile after the Bugsnag pod:

pod 'Bugsnag'
plugin 'cocoapods-bugsnag'

The Bugsnag pod won’t exist here if you’re using @bugsnag/react-native.

Then, install with:

pod install

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

Adding a build phase manually

To add an upload build phase to your project manually:

  1. From the “Build Phases” screen, click the plus in the top left, then select “New Run Script Phase”

  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:

    api_key = 'your-api-key-here'
    
    if ENV['ENABLE_USER_SCRIPT_SANDBOXING'] == 'YES'
      count = ENV['SCRIPT_INPUT_FILE_COUNT'].to_i
      abort 'error: dSYMs must be specified as build phase "Input Files" because ENABLE_USER_SCRIPT_SANDBOXING is enabled' unless count > 0
      dsyms = []
      for i in 0 .. count - 1
        dsym = ENV["SCRIPT_INPUT_FILE_#{i}"]
        if File.exist? dsym
          dsyms.append dsym
        else
          abort "error: cannot read #{dsym}" unless ENV['DEBUG_INFORMATION_FORMAT'] != 'dwarf-with-dsym'
        end
      end
    else
      dsyms = Dir["#{ENV['DWARF_DSYM_FOLDER_PATH']}/*/Contents/Resources/DWARF/*"]
    end
    
    dsyms.each do |dsym|
      Process.detach Process.spawn('/usr/bin/curl', '--http1.1',
        '-F', "apiKey=#{api_key}",
        '-F', "dsym=@#{dsym}",
        '-F', "projectRoot=#{ENV['PROJECT_DIR']}",
        'https://upload.bugsnag.com/dsym'
      )
    end
    
  4. Uncheck the “Based on dependency analysis” option.

  5. Add the following to the “Input Files” list:

    $(DWARF_DSYM_FOLDER_PATH)/$(DWARF_DSYM_FILE_NAME)/Contents/Resources/DWARF/$(TARGET_NAME)
    

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

If you have enabled Xcode 14’s ENABLE_USER_SCRIPT_SANDBOXING build setting, all your app’s dSYMs (including those for embedded frameworks) must be specified as Input Files.

Troubleshooting missing dSYM files

When BugSnag receives an event and dSYM files are not available to symbolicate the stacktrace, the stackframes will show raw memory addresses. Finding and uploading the missing dSYM files triggers symbolication of existing events in BugSnag: revealing human-readable function names, file paths and line numbers in place of memory addresses.

The dSYM files for a particular build of an app are available on the machine where it was compiled. The following steps may help in finding and uploading those files:

  1. A list of missing dSYM files is available on the dSYMS page in your BugSnag project’s settings. 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.