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.

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.

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

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

--upload-server ""

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.

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

If you’re not using 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 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'
      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
          abort "error: cannot read #{dsym}" unless ENV['DEBUG_INFORMATION_FORMAT'] != 'dwarf-with-dsym'
      dsyms = Dir["#{ENV['DWARF_DSYM_FOLDER_PATH']}/*/Contents/Resources/DWARF/*"]
    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']}",
  4. Uncheck the “Based on dependency analysis” option.

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


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 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
    $ 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 bugsnag-dsym-upload set the --symbol-map argument to the directory containing the symbol maps:

$ bugsnag-dsym-upload --symbol-map path/to/BCSymbolMaps

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