Advanced Crash Report Symbolication

This guide assumes you’ve read our Bug Reporting guide and need to manually symbolicate a crash report. For most cases, simply ensuring our corresponding .dSYM files are uploaded to your crash reporting service will be sufficient.

If you have a matching binary, crash log, and .dSYM file, you can symbolicate (add debugging symbols to) the crash log manually using Xcode’s symbolicatecrash tool:

/Applications/Xcode.app/Contents/SharedFrameworks/DVTFoundation.framework/Versions/A/Resources/symbolicatecrash

Open bash and export your DEVELOPER_DIR as an environment variable:

Terminal window
export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"

Place your .crash, .app, and .dSYM files (your app and dynamic frameworks) in the same directory and run the following:

Terminal window
symbolicatecrash MyAppCrash.crash ./MyApp.app/MyApp > Symbolicated.crash

If this doesn’t work, you can use -v to get more information. In most cases, the reason this doesn’t work is the binary doesn’t match the .dSYM files. Ensure that Spotlight indexing is enabled for the location you run this on.

How to Symbolicate Manually with atos

This method uses atos(opens in a new tab) and is a little more advanced, but it’s worth trying if you’re having trouble with the other methods.

The atos command converts numeric addresses to their symbolic equivalents. If full debug symbol information is available — for example, in an .app.dSYM sitting beside an .app, then the output of atos will include the file name and source line number information.

You need the following files in the same directory:

  • PSPDFKit.framework
  • PSPDFKit.framework.ios-arm64.dSYM
  • mycrash.crash

Check if these are all from the same build by ensuring the UUIDs within them match. To extract the UUIDs from the binary and the .dSYM file, use the following:

Terminal window
dwarfdump PSPDFKit.framework/PSPDFKit -u
dwarfdump PSPDFKit.framework.ios-arm64.dSYM -u

Look for the UUID of the appropriate architecture of the crash log you’re examining — for example:

UUID: 35DA91E3-AECE-300A-AB16-158B42FF78DB (arm64) PSPDFKit.framework.dSYM/Contents/Resources/DWARF/PSPDFKit

In the Binary Images section of the crash log, the UUID of the framework binary has the UUID inside <...>, lowercased and without dashes — for example:

Terminal window
0x1003d8000 -        0x100e47fff +PSPDFKit arm64  <35da91e3aece300aab16158b42ff78db> /Some Path to .../MyApp.app/Frameworks/PSPDFKit.framework/PSPDFKit

The first column is the load address. In this case, it’s 0x1003d8000. The load address is given to atos so it can work out the correct offset in the .dSYM file, like so:

atos -arch arm64 -o ./PSPDFKit.framework/PSPDFKit -l 0x1003d8000

With the above line, atos will read lines from stdin and attempt to symbolicate the line. However, we need to find an address to give it:

Terminal window
   Thread 4 Crashed:
           0   PSPDFKit  0x000000010079e5b8 std::__1::__hash_table<std::__1::__hash_value_type<void*, objc_object* __weak>...

Instead of letting atos read from stdin, we can instead pass addresses immediately. After the load address, we can pass a whitespace-separated list of addresses to symbolicate:

atos -arch arm64 -o ./PSPDFKit.framework/PSPDFKit -l 0x1003d8000 0x000000010079e5b8

atos should then print out the line.

ℹ️ Note: The same procedure applies to PSPDFKitUI.framework.

Solving Symbolication Problems

There are several resources that help if you have trouble symbolicating your crash logs.