crash-debugging

What this skill does

# Crash Debugging Skill

**Comprehensive guide to iOS crash analysis and debugging**

## Quick Reference

| Task | Tool/Command | Location |
|------|--------------|----------|
| View crash logs | Console.app | macOS Application |
| Retrieve simulator crashes | ~/Library/Logs/DiagnosticReports/ | File system |
| Symbolicate crash | atos | Command line |
| Find dSYM files | Xcode Organizer / DerivedData | Xcode |
| Analyze crash type | Stack trace patterns | Crash log |

## 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

| Exception Type | Meaning | Common Cause |
|----------------|---------|--------------|
| EXC_BAD_ACCESS | Invalid memory access | Dangling pointer, use-after-free |
| SIGABRT | Process aborted | Assertion failure, force unwrap nil |
| EXC_BREAKPOINT | Breakpoint hit | Swift runtime error, fatal error |
| SIGILL | Illegal instruction | Corrupted code, wrong architecture |
| SIGSEGV | Segmentation fault | Memory corruption |
| SIGBUS | Bus error | Unaligned memory access |

## Workflows

### Workflow 1: Crash Log Retrieval

#### From Simulator

**Step 1: Locate Crash Logs**

```bash
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:

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

**Step 3: Read Crash Log**

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

#### From Console.app (Recommended)

**Step 1: Open Console.app**

```bash
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:**

```bash
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**

```bash
# 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**

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

**Output:**
```
ViewController.loginButtonTapped() (in MyApp) (ViewController.swift:45)
```

**Step 3: Symbolicate Multiple Addresses**

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

#### Batch Symbolication (symbolicatecrash)

**Symbolicate Entire Crash Log:**

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

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

**Verify Symbolication:**

```bash
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-