/crash-debugging

name: crash-debugging
description: Crash log analysis, symbolication, and debugging workflows for iOS apps. Use when investigating app crashes, analyzing crash reports, symbolicating stack traces, or identifying root causes. Covers crash log retrieval, symbolication with dSYM files, stack trace analysis, and common crash patterns.
version: 0.0.1
token_cost: ~40

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

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="/App