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
Open bash and export your
DEVELOPER_DIR as an environment variable:
.dSYM files (your app and dynamic frameworks) in the same directory and run the following:
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.
If your application ships with bitcode, Apple will recompile it on its servers before pushing it to the App Store. This will modify symbol positions and generate a new
.dSYM file. Apple lets you download these
.dSYM files from its server, and there are also third-party tools, like
fastlane refresh_dsyms, that can automate this process.
How to Symbolicate Manually with atos
This method uses
atos and is a little more advanced, but it’s worth trying if you’re having trouble with the other methods.
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:
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:
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:
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:
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
Solving Symbolication Problems
There are several resources that help if you have trouble symbolicating your crash logs.