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.

By default, sentry-cli uploads executables, libaries and frameworks alongside the dSYM files. This is required to achieve high quality stack traces for Minidump crash reports. For iOS apps using our Cocoa SDK this is not required.

Since dSYMs have a unique signature, you do not need to associate them with releases. sentry-cli uses their UUID to associate symbols with crash events.

Example for iOS apps (only upload dSYMs):

$ sentry-cli upload-dif -t dsym --no-bin .

> Found 1 debug information file
> Prepared debug information file for upload
> Uploaded 1 missing debug information file
> File processing complete:

     OK 27d16d76-924d-3a1d-b471-604e3b70fb0c (MyApp; x86_64 debug companion)

Example for applications using minidumps (upload dSYM and binaries):

$ sentry-cli upload-dif -t dsym .

> Found 2 debug information files
> Prepared debug information files for upload
> Uploaded 2 missing debug information files
> File processing complete:

     OK 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable)
     OK 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion)

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

Upload Options

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


Do not scan for stack unwinding information. Specify this flag for builds with disabled FPO, or when stackwalking occurs on the device. This usually excludes executables and libraries. They might still be uploaded, if they contain debug information. When using the Cocoa SDK, this flag can safely be activated since Sentry does not require unwind information.


Do not scan for debug information. This will usually exclude debug companion files. They might still be uploaded, if they contain stack unwinding information.


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.