iOS Crash Log Debugging

Crash Debugging Skill

Comprehensive guide to iOS crash analysis and debugging

Quick Reference

Overview

Crash debugging transforms cryptic crash logs into actionable insights. This skill covers:

• Retrieving crash logs from simulators and devices
• Understanding crash log structure
• Symbolicating stack traces for readable function names
• Identifying common crash patterns
• Determining root causes

When to Use This Skill

Use this skill when:

• App crashes during testing or development
• Received crash reports from users or TestFlight
• CI/CD pipeline reports test crashes
• Need to symbolicate production crash logs
• Investigating memory issues or crashes

Don't use for:

• Build failures (see xcode-workflows)
• Test assertion failures (see ios-testing-patterns)
• UI debugging (see ui-automation-workflows)

Key Concepts

Crash Logs vs Diagnostic Reports

Crash Logs:

• Generated when app terminates unexpectedly
• Include exception type, stack trace, register state
• Stored in DiagnosticReports directory
• Named: AppName_YYYY-MM-DD-HHMMSS_DeviceName.crash

Diagnostic Reports:

• Broader category including crashes, spins, hangs
• May include system diagnostics
• Same location as crash logs

Symbolication Process

Unsymbolicated:

0   MyApp    0x0000000102a3c4f8 0x102a38000 + 17656
1   MyApp    0x0000000102a3d1a4 0x102a38000 + 20900

Symbolicated:

0   MyApp    0x0000000102a3c4f8 ViewController.loginButtonTapped() + 120
1   MyApp    0x0000000102a3d1a4 ViewController.viewDidLoad() + 84

Symbolication Requirements:

1. dSYM file matching the build UUID
2. Binary (MyApp.app/MyApp)
3. Crash log with memory addresses

Stack Traces and Debugging Symbols

Stack Trace:

• List of function calls leading to crash
• Ordered from crash point (top) to app entry (bottom)
• Each line contains: frame number, binary name, address, symbol + offset

Debugging Symbols (dSYM):

• Separate file containing symbol information
• Maps memory addresses to function names
• Generated during build (if "Debug Information Format" = "DWARF with dSYM")
• Essential for crash analysis

Common Crash Types

Workflows

Workflow 1: Crash Log Retrieval

From Simulator

Step 1: Locate Crash Logs

open ~/Library/Logs/DiagnosticReports/

Directory Structure:

DiagnosticReports/
├── MyApp_2025-11-06-143022_Conors-MacBook.crash
├── MyApp_2025-11-06-140511_Conors-MacBook.crash
└── ...

Step 2: Identify Recent Crash

Sort by date modified, or filter by app name:

ls -lt ~/Library/Logs/DiagnosticReports/ | grep MyApp | head -5

Step 3: Read Crash Log

cat ~/Library/Logs/DiagnosticReports/MyApp_2025-11-06-143022_Conors-MacBook.crash

From Console.app (Recommended)

Step 1: Open Console.app

open -a Console

Step 2: Filter Logs

• Click "Crash Reports" in sidebar
• Search for app name
• Click crash report to view

Advantages:

• Real-time monitoring
• Better filtering and search
• Automatic refresh

From Device (via Xcode)

Step 1: Connect Device

Step 2: Open Devices and Simulators

• Xcode → Window → Devices and Simulators
• Select device

Step 3: View Device Logs

• Click "View Device Logs"
• Find crash report
• Right-click → Export

Workflow 2: Symbolication

Automatic Symbolication (Xcode)

Step 1: Locate dSYM

Xcode automatically symbolicates if:

1. dSYM is in Spotlight index
2. dSYM UUID matches crash log

Check dSYM UUID:

dwarfdump --uuid /path/to/MyApp.app.dSYM

Check Crash Log UUID:

Binary Images:
0x102a38000 - 0x102a4bfff MyApp arm64  <12345678-1234-1234-1234-123456789abc>

UUIDs must match for symbolication.

Step 2: Import to Xcode

If auto-symbolication fails:

1. Xcode → Window → Organizer
2. Select "Crashes" tab
3. Drag crash log into window
4. Xcode symbolicates automatically (if dSYM available)

Manual Symbolication (atos)

Step 1: Find Required Files

# App binary
APP_BINARY="/path/to/MyApp.app/MyApp"

# dSYM file
DSYM_FILE="/path/to/MyApp.app.dSYM/Contents/Resources/DWARF/MyApp"

# Load address (from crash log "Binary Images" section)
LOAD_ADDRESS="0x102a38000"

Step 2: Symbolicate Address

atos -arch arm64 -o "$DSYM_FILE" -l "$LOAD_ADDRESS" 0x0000000102a3c4f8

Output:

ViewController.loginButtonTapped() (in MyApp) (ViewController.swift:45)

Step 3: Symbolicate Multiple Addresses

atos -arch arm64 -o "$DSYM_FILE" -l "$LOAD_ADDRESS" \
  0x0000000102a3c4f8 \
  0x0000000102a3d1a4 \
  0x0000000102a3e220

Batch Symbolication (symbolicatecrash)

Symbolicate Entire Crash Log:

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

symbolicatecrash MyApp.crash MyApp.app.dSYM > MyApp_symbolicated.crash

Verify Symbolication:

grep -A 10 "Thread 0 Crashed" MyApp_symbolicated.crash

Should show function names, not just addresses.

Workflow 3: Stack Trace Analysis

Reading a Crash Log

Crash Log Structure:

Incident Identifier: 12345678-1234-1234-1234-123456789ABC
CrashReporter Key:   ABCDEF1234567890
Hardware Model:      iPhone15,2
Process:             MyApp [12345]
Path:                /private/var/containers/Bundle/Application/.../MyApp.app/MyApp
Identifier:          com.example.MyApp
Version:             1.0 (1)
Code Type:           ARM-64
Parent Process:      launchd [1]

Date/Time:           2025-11-06 14:30:22.123 +0000
OS Version:          iOS 17.0 (21A5326a)
Report Version:      104

Exception Type:      EXC_BAD_ACCESS (SIGSEGV)
Exception Subtype:   KERN_INVALID_ADDRESS at 0x0000000000000000
Termination Reason:  SIGNAL 11 Segmentation fault: 11
Terminating Process: exc handler [12345]

Triggered by Thread: 0

Thread 0 Crashed:
0   MyApp              0x0000000102a3c4f8 ViewController.loginButtonTapped() + 120
1   MyApp              0x0000000102a3d1a4 ViewController.viewDidLoad() + 84
2   UIKitCore          0x00000001b2e4c3a0 -[UIViewController loadViewIfRequired] + 928
...

Thread 1:
0   libsystem_kernel.dylib  0x00000001a2b3c4a8 __workq_kernreturn + 8
...

Binary Images:
0x102a38000 - 0x102a4bfff MyApp arm64  <12345678-1234-1234-1234-123456789abc>
...

Key Sections to Analyze

1. Exception Type

Exception Type:      EXC_BAD_ACCESS (SIGSEGV)
Exception Subtype:   KERN_INVALID_ADDRESS at 0x0000000000000000

• EXC_BAD_ACCESS: Memory access violation
• KERN_INVALID_ADDRESS: Address doesn't exist (null pointer)
• 0x0000000000000000: Accessing address zero (dereferencing nil)

2. Crashed Thread

Thread 0 Crashed:
0   MyApp              0x102a3c4f8 ViewController.loginButtonTapped() + 120
1   MyApp              0x102a3d1a4 ViewController.viewDidLoad() + 84

• Frame 0 is crash location
• Read from top to bottom (most recent to oldest)
• Identify last app frame before system frames

3. Binary Images

0x102a38000 - 0x102a4bfff MyApp arm64  <12345678-1234-1234-1234-123456789abc>

• Load address: 0x102a38000
• UUID: 12345678-1234-1234-1234-123456789abc
• Architecture: arm64

Workflow 4: Root Cause Identification

Step 1: Identify Crash Type

Match exception type to common patterns (see below).

Step 2: Locate Crash Point

Find the topmost frame in your app's code:

Thread 0 Crashed:
0   MyApp              0x102a3c4f8 ViewController.loginButtonTapped() + 120  ← START HERE
1   MyApp              0x102a3d1a4 ViewController.viewDidLoad() + 84

Step 3: Analyze Code Path

1. Open file at crash location (ViewController.swift:45)
2. Examine function loginButtonTapped()
3. Check for:
   • Optional unwrapping (! or ?)
   • Array/dictionary access
   • Object references
   • Memory management

Step 4: Reproduce Locally

1. Set breakpoint at crash location
2. Follow stack trace path
3. Inspect variables and state
4. Identify null/invalid values

Step 5: Validate Fix

1. Apply fix
2. Build and test
3. Verify no regression
4. Monitor for related crashes

Common Crash Patterns

EXC_BAD_ACCESS (Memory Issues)

Signature:

Exception Type:  EXC_BAD_ACCESS (SIGSEGV)
Exception Codes: KERN_INVALID_ADDRESS at 0x0000000000000000

Common Causes:

1. Dereferencing Nil (Swift)

// Crash:
let user: User? = nil
let name = user!.name  // EXC_BAD_ACCESS

// Fix:
if let name = user?.name {
    // Use name safely
}

2. Dangling Pointer (Objective-C)

// Crash:
@property (nonatomic, unsafe_unretained) id delegate;  // Dangerous
[self.delegate callMethod];  // Delegate deallocated → EXC_BAD_ACCESS

// Fix:
@property (nonatomic, weak) id<MyDelegate> delegate;

3. Use-After-Free

// Crash:
var buffer = UnsafeMutablePointer<Int>.allocate(capacity: 10)
buffer.deallocate()
buffer[0] = 42  // EXC_BAD_ACCESS

// Fix:
buffer[0] = 42
buffer.deallocate()

Debugging:

• Enable Address Sanitizer (Scheme → Diagnostics → Address Sanitizer)
• Check for weak vs unsafe_unretained references
• Verify object lifecycle

SIGABRT (Assertion Failures)

Signature:

Exception Type:  EXC_CRASH (SIGABRT)
Exception Codes: 0x0000000000000000, 0x0000000000000000
Termination Reason: Namespace SIGNAL, Code 6 Abort trap: 6

Common Causes:

1. Force Unwrap Nil (Swift)

// Crash:
let value = dictionary["key"]!  // key doesn't exist → SIGABRT

// Stack trace shows:
Fatal error: Unexpectedly found nil while unwrapping an Optional value

// Fix:
if let value = dictionary["key"] {
    // Use value
}

2. Array Index Out of Bounds

// Crash:
let items = [1, 2, 3]
let item = items[10]  // Index out of range → SIGABRT

// Fix:
if items.indices.contains(10) {
    let item = items[10]
}

3. NSException (Objective-C)

// Crash:
[NSException raise:@"InvalidState" format:@"Unexpected condition"];

// Stack trace shows:
*** Terminating app due to uncaught exception 'InvalidState'

Debugging:

• Read error message in crash log (very descriptive)
• Check preconditions and assertions
• Validate input data

EXC_BREAKPOINT (Swift Errors)

Signature:

Exception Type:  EXC_BREAKPOINT (SIGTRAP)
Exception Codes: 0x0000000000000001, 0x00000001a2b4c8d0

Common Causes:

1. Fatal Error

// Crash:
guard let user = currentUser else {
    fatalError("User must be logged in")  // EXC_BREAKPOINT
}

// Stack trace shows:
Fatal error: User must be logged in

// Fix:
guard let user = currentUser else {
    print("Error: User not logged in")
    return
}

2. Type Cast Failure (as!)

// Crash:
let value = anyValue as! String  // Value is not String → EXC_BREAKPOINT

// Fix:
if let value = anyValue as? String {
    // Use value
}

3. Precondition Failure

// Crash:
precondition(array.count > 0, "Array must not be empty")

// Fix:
if array.count > 0 {
    // Proceed safely
}

Debugging:

• Read fatal error message in crash log
• Review force casts (as!)
• Check preconditions and guards