How to manually symbolicate crash on Apple platforms

22. 12. 2023

Everyone knows that feeling when you get a “raw” crash and you don’t know what to do — there is nothing more than a lot of addresses. It can happen either because of a crash service fail (e.g. Fabric) or you can get a raw crash from testers, clients or customers’ devices.

DON’T worry. The process of symbolicating return addresses back into human-readable text is rather easy. It takes only a few steps that you can follow in this text. If you are lazy to read, our Youtube video can be of great help ????.

Important Files

First of all, you need two files – Crash and dSYM file. You probably already have the crash file if you are reading this article. So let’s go find dSYM file(s).

    1. You can find .dSYM file in .appfile. In case you can see only .ipa file, decompress it just like an ordinary .zip file and extract .app file from it.
    2. .dSYMfile can be also found in .xarchive file. If you have .app file you can find .dSYM file in this package. Also if you have .ipa file you can extract .app file by decompressing it. It’s just like .zip file.
    3. The last option is a derived data folder. You can find .dSYM file by the following way: DerivedData -> “YourApp” -> Build -> Products -> “YourDevice”



  1. In the beginning of symbolicating process you need to find the command line tool provided by Apple. The tool is called “symbolicatecrash” and is shipped with Xcode. Open Terminal and write this command:
    $ find /Applications -name symbolicatecrash
    You will see something like that:
    Find the path which contains DVTFoundation.framework. Copy the full path to the clipboard. You will use it later.
  2. In the next step you set the DEVELOPER_DIR environment variable. Write this command: $ export DEVELOPER_DIR=”/Applications/”
  3. Finally, this is the last step of the process. Paste the previously copied value to the terminal (the path of symbolicatecrash tool). This tool takes two arguments. The first argument is the path to your crash file. The second argument is the path to the dSYM file. So, the final command may look like this: $/Applications/ MyAwesomeCrash.crash MyAwesomeApp.dSYM > Symbolicated.crash

You are done! Pretty simple, right? ????
At this moment Symbolicated.crash file contains human-readable text. You can see your class name, method name, and file name.



Multiple dSYMs

Crash can occur either in a third-party framework or your own framework. So, you have .dSYM of your App and another .dSYM file of your framework. Symbolicating this type of crash is very simple. The second parameter of command is .dSYM path. It can be a path to folder which contains multiple .dSYMs. It will use all dSYMs in that folder to symbolicate your crash.

I have a confession – I lied a little bit to you. The second parameter of symbolicatecrash tool is rather optional, so you can freely omit it. The symbolicatecrash tool finds correct dSYMs files on your disk and then use them for symbolicating your crash. So, the second parameter is used only for defining another path that will help to search dSYMs files (e.g. flash disc). Following such a method, you can be sure that the tool will use the same path as well…

If it doesn’t work

As it happens, sometimes things don’t work out the way you want them to.. You have to check whether UUID of your .dSYM, .app and crash match together. It’s also simple – use another command line tool. This tool is called dwarfdump. You can easily extract UUID out of that files with this tool. If you have .dSYM file named like this “MyAwesomeApp.dSYM” you can write this command in terminal:

$ dwarfdump –uuid MyAwesomeApp.dSYM/Contents/Resources/DWARF/MyAwesomeApp

It returns something like this:

Then you can check if UUIDs match (I mean if crash contains UUID from .dSYM file) by this command:

grep -o -i ‘2d189bea-ffcf-36ef-b8d1-fd4220374034’ MyAwesomeCrash.crash

If you want to understand more deeply this topic, please visit the official Apple documentation.

Do you need more detailed help? Book a consultation:
Let’s chat about it

Do you want more?

We share the world of software development on our Instagram. Join us 🙂



We also tend to look for Android dev (iOS as well), but there are also chances for a project manager or a tester. Send us an e-mail: [email protected].

10 Entrepreneurship Lessons Worth Thousands of Dollars

Instead of great success we have experienced great entrepreneurship lessons (for now). It also transformed me, a person who has …

Read article

Unique Czech words reflecting coronavirus now also with English explanations as Flashcard quiz in Vocabulary Miner

  Project Čestina 2.0 covering a variety of the modern Czech language with its slangs and new words has joined …

Read article

Performance of built-in higher-order functions Map, Filter, Reduce, and flatMap vs. for-in loop in Swift

  The most popular higher-order functions are map, filter, and reduce. We all use them since we think that syntax …

Read article