dSYM Upload

sentry-cli can upload dSYM files to Sentry to allow symbolication of iOS app crashes. It is also used behind the scenes if you use systems like fastlane or build system integrations.

For general information about dSYM handling, please refer to Uploading Debug Symbols as well as Debug Information Files for an introduction.

Basic Upload

Use upload-dif to upload dSYM files and specify the dsym type. If invoked during an Xcode build step, sentry-cli will automatically pick up the DWARF_DSYM_FOLDER_PATH environment variable. Otherwise, provide the path to a dSYM or folder containing dSYMs as command line argument.

Since dSYMs have a unique signature, you do not need to associate them with releases. However, the CLI will automatically scan for a Info.plist in the path provided to find the release. If a release is found, the dSYMS are associated automatically. Even without this association, the uploaded dSYMs will be used for symbolication.


$ sentry-cli upload-dif -t dsym .

Upload Options

There are a few options you can supply for the upload process


Exclude executables and libraries from the upload and search for dSYM files only. For iOS apps, this setting can safely be activated since Sentry does not requrie them for symbolication.


Search for dSYMs in derived data folder. This is the default location Xcode stores its build output in.


By default, sentry-cli will open and search ZIP archives for dSYMs. This is especially useful when downloading builds from iTunes Connect. Use this switch to disable if your search paths contain large ZIP archives without dSYMs to speed up the search.


This option forces the dSYM upload to happen in foreground. This only affects uploads invoked from Xcode build steps. By default, the upload process will detach when started from Xcode and finish in the background. If you need to debug the upload process it might be useful to force the upload to run in the foreground.


Overrides the search path for Info.plist, usefule if it is located in a non-standard location.


This parameter prevents Sentry from triggering reprocessing right away. It can be useful under rare circumstances where you want to upload files in multiple batches and you want to ensure that Sentry does not start reprocessing before some optional dsyms are uploaded. Note though that someone can still in the meantime trigger reprocessing from the UI.


Resolve hidden symbols in iTunes Connect builds using BCSymbolMaps. This is needed to symbolicate crashes if symbols were not uploaded to Apple when publishing the app in the AppStore.

Symbol Maps

If you are hiding debug symbols from Apple the debug files will not contain many useful symbols. In that case the sentry-cli upload will warn you that it needs BCSymbolMaps:

$ sentry-cli upload-dif ...
> Found 34 debug information files
> Warning: Found 10 symbol files with hidden symbols (need BCSymbolMaps)

In this case, you need the BCSymbolMaps that match your files. Normally, these get generated by the Xcode build process. Supply the --symbol-maps parameter and point it to the folder containing the symbol maps:

$ sentry-cli upload-dif --symbol-maps path/to/symbolmaps path/to/debug/symbols