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.
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.
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.
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.
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.
If you’re not using the CocoaPods plugin, adding a build phase to your project can be configured manually.
From the “Build Phases” screen, click the plus in the top left, then select “New Run Script Phase”
Expand the newly added “Run Script” section, and set the shell to
/usr/bin/ruby
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/'
)
end
Uncheck the “Based on dependency analysis” option.
Add the following to the 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.
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.
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.
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.
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
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.
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 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