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:

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 the BugSnag CLI

Our command line tool can be integrated into your build/CI process with one simple command referencing your Xcode project to find and upload dSYM files following a build:

$ bugsnag-cli upload xcode-build path/to/my-project.xcodeproj

Where possible the information required for the upload, including the path to the dSYM, will be obtained from the project file. However all inputs can be provided as command-line options to customize it for your app’s build. See the xcode-build command reference page for available options and overrides.

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)
   

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.

Once added, your dSYM files will be automatically uploaded during a build.

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. In your BugSnag project’s settings, go to the dSYMS page which shows the UUIDs of missing dSYM files.

You can then use the mdfind tool on macOS to locate the missing dSYM file(s) using the UUID and upload it – or the whole directory – using the BugSnag command line tool.

$ mdfind YOUR_UUID_HERE

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