iOS Symbolication: Understanding Crash Logs and Tools

iOS Symbolication

Preface

iOS developers are familiar with symbolication, yet most articles only cover fragments; this post aims to give a complete overview based on the author’s work experience. For questions, contact: [email protected]

All examples and logs in this article target iOS projects.

Table of Contents

What is Symbolication

Why Symbolicate

Crash File Analysis

Symbolication Process

Extensions

Reference Documents

Afterword

What is Symbolication

Symbolication converts machine‑level hexadecimal addresses in iOS crash logs into human‑readable symbols (function names, file names, line numbers) so developers can locate the source of an exception quickly.

Levels of Symbolication

Full Symbolication

Thread 0 name:  Dispatch queue: com.apple.main-thread
Thread 0 Crashed:
0   libswiftCore.dylib                0x00000001bd38da70 specialized _fatalErrorMessage+ 2378352 ...

Partial Symbolication

Thread 0 name:  Dispatch queue: com.apple.main-thread
Thread 0 Crashed:
0   libswiftCore.dylib                0x00000001bd38da70 0x1bd149000 + 2378352 ...

Unsymbolicated

Thread 0 name:  Dispatch queue: com.apple.main-thread
Thread 0 Crashed:
0   libswiftCore.dylib                0x00000001bd38da70 0x1bd149000 + 2378352 ...

Why Symbolicate

Symbolication enables developers to quickly find the offending stack frame, pinpoint the bug, and restore normal program operation.

Crash File Analysis

Understanding a crash log starts with knowing each field’s meaning.

Incident Identifier: xxxxx-xxxx-xxxx-xxxx-89D2A9086DFE
CrashReporter Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Hardware Model: iPhone10,3
Process: bdnews [22785]
Path: /private/var/containers/Bundle/Application/.../bdnews.app/bdnews
Identifier: com.bd.newspaper.inhouse
Version: 224.1 (6.6.20)
Code Type: ARM-64 (Native)
...

Incident Identifier – unique ID of the crash report.

CrashReporter Key – key for the report.

Hardware Model – device type.

Process – executable name.

Path – location of the binary on the device.

Identifier – bundle ID.

Version – CFBundleVersion.

Code Type – CPU architecture (ARM‑64).

Exception Type – e.g., EXC_CRASH (SIGKILL) .

Termination Reason – why the OS terminated the process.

Triggered by Thread – the thread that caused the crash.

The stack trace is listed from top to bottom, showing thread index, binary image name, load address, and offset.

Binary Image Information

Address range of the loaded binary.

Binary name.

CPU architecture.

UUID – matches the dSYM UUID.

Path on device.

Symbolication Process

Required Files

Three elements are mandatory:

Crash log file (usually .crash ).

dSYM file (debug symbols).

Symbolication tool (Apple’s symbolicatecrash or atos ).

Obtaining the Crash File

During development: Xcode → Window → Devices and Simulators → View Device Logs.

From a production device: Settings → Privacy → Analytics & Improvements → Analytics Data.

Obtaining dSYM

If Bitcode is enabled, download dSYM from App Store Connect → Activity → select the matching build.

If Bitcode is disabled, locate the .app.dSYM inside the .xcarchive via Xcode → Organizer → Show in Finder → Show Package Contents.

Symbolication Tools

symbolicatecrash

Apple‑provided command‑line tool. Find it with:

// find symbolicatecrash for Applications
$ sudo find /Applications -name symbolicatecrash
# Example paths:
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/Library/PrivateFrameworks/DVTFoundation.framework/symbolicatecrash

Typical usage:

$ export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
$ symbolicatecrash -d <path_to_dsym> -o <output_path> <path_to_crash_report>

atos

Converts a hexadecimal address to a symbol with line number.

atos -arch <arch> -o <path_to_dsym>/Contents/Resources/DWARF/<binary> -l <load_address> <address_to_symbolicate>

Example:

atos -arch arm64 -o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp -l 0x00000001c4fe7000 0x00000001a2d6e29c

Result:

__63-[GCDAsyncUdpSocket asyncResolveHost:port:withCompletionBlock:]_block_invoke.118 (in MyApp) (GCDAsyncUdpSocket.m:1209)
- [BDAboutController tapButton:atIndex:] (in MyApp) (BDAboutController.m:251)

Extensions

Third‑party APM solutions also rely on symbolication; however, discrepancies may occur, so manual verification is recommended.

Reference Documents

Apple – Adding Identifiable Symbol Names to a Crash Report

Apple – Examining the Fields in a Crash Report

StackOverflow – How is a dSYM file created?

GitHub – litesymbols

Afterword

Symbolication is routine, but mastering it speeds up debugging and reduces downtime. This guide is only the beginning; many more pitfalls await.