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.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Comprehensive guide to iOS crash analysis and debugging
| 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 |
Crash debugging transforms cryptic crash logs into actionable insights. This skill covers:
Use this skill when:
Don't use for:
Crash Logs:
AppName_YYYY-MM-DD-HHMMSS_DeviceName.crashDiagnostic Reports:
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:
Stack Trace:
Debugging Symbols (dSYM):
| 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 |
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
Step 1: Open Console.app
open -a Console
Step 2: Filter Logs
Advantages:
Step 1: Connect Device
Step 2: Open Devices and Simulators
Step 3: View Device Logs
Step 1: Locate dSYM
Xcode automatically symbolicates if:
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:
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
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.
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>
...
1. Exception Type
Exception Type: EXC_BAD_ACCESS (SIGSEGV)
Exception Subtype: KERN_INVALID_ADDRESS at 0x0000000000000000
2. Crashed Thread
Thread 0 Crashed:
0 MyApp 0x102a3c4f8 ViewController.loginButtonTapped() + 120
1 MyApp 0x102a3d1a4 ViewController.viewDidLoad() + 84
3. Binary Images
0x102a38000 - 0x102a4bfff MyApp arm64 <12345678-1234-1234-1234-123456789abc>
0x102a3800012345678-1234-1234-1234-123456789abcarm64Match exception type to common patterns (see below).
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
loginButtonTapped()! or ?)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:
weak vs unsafe_unretained referencesSignature:
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:
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:
as!)Signature:
Exception Type: EXC_CRASH (SIGKILL)
Exception Codes: 0x0000000000000000, 0x0000000000000000
Termination Reason: Namespace SPRINGBOARD, Code 0x8badf00d
0x8badf00d = "ate bad food" = Watchdog timeout
Common Causes:
1. Main Thread Blocking
// Crash:
func viewDidLoad() {
super.viewDidLoad()
Thread.sleep(forTimeInterval: 30) // Blocks main thread → Watchdog kills app
}
// Fix:
func viewDidLoad() {
super.viewDidLoad()
DispatchQueue.global().async {
Thread.sleep(forTimeInterval: 30)
}
}
2. Launch Time Timeout
App takes too long to launch (>20 seconds).
Fix:
3. Suspend/Resume Timeout
App doesn't respond to backgrounding/foregrounding.
Fix:
applicationDidEnterBackground quicklyDebugging:
Signature:
Exception Type: EXC_RESOURCE
Exception Subtype: MEMORY
Exception Codes: 0x0000000000000000, 0x0000000000000000
Termination Reason: Namespace JETSAM, Code 0xdead10cc
Common Causes:
1. Memory Leak
// Leak:
class ViewController {
var closure: (() -> Void)?
func setup() {
closure = {
self.doSomething() // Retain cycle
}
}
}
// Fix:
closure = { [weak self] in
self?.doSomething()
}
2. Large Allocations
// Crash:
let hugeArray = Array(repeating: Data(count: 1_000_000), count: 1000)
// Fix:
// Process in chunks, release memory incrementally
Debugging:
Problem: Stack trace shows addresses, not function names
Cause: Missing or mismatched dSYM file
Solutions:
# List all dSYMs in DerivedData
find ~/Library/Developer/Xcode/DerivedData -name "*.dSYM" -type d
# Check UUID
dwarfdump --uuid /path/to/MyApp.app.dSYM
Compare dSYM UUID with crash log Binary Images UUID. They must match exactly.
Enable "Archive" in scheme settings to preserve dSYMs for releases.
For App Store builds:
Problem: Stack trace incomplete or truncated
Causes:
Solutions:
Build Settings:
{
"operation": "build",
"scheme": "MyApp",
"configuration": "Debug"
}
Add -Xswiftc -Ounchecked to reduce optimizations.
Problem: Crash in UIKit, Foundation, or other system framework
Stack Trace:
Thread 0 Crashed:
0 UIKitCore 0x00001b2e4c3a0 -[UIView layoutSubviews] + 928
1 UIKitCore 0x00001b2e5d1c4 -[UIView setNeedsLayout] + 84
2 MyApp 0x00102a3c4f8 ViewController.updateUI() + 45
Analysis:
Solutions:
Before system call, validate:
Auto Layout issues often cause UIKit crashes:
Xcode → Breakpoints → + → Exception Breakpoint
Problem: Crash in external library/framework
Stack Trace:
Thread 0 Crashed:
0 Alamofire 0x00001054a3c4f8 RequestAdapter.adapt() + 120
1 MyApp 0x00102a3c4f8 NetworkManager.fetchData() + 45
Solutions:
Ensure compatible version:
Verify:
In Podfile or SPM:
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['DEBUG_INFORMATION_FORMAT'] = 'dwarf-with-dsym'
end
end
end
If library bug:
Launch:
open -a Console
Filter by App:
Export: Right-click crash → "Reveal in Finder" → Copy file
Basic Usage:
atos -arch arm64 \
-o /path/to/App.app.dSYM/Contents/Resources/DWARF/App \
-l 0x100000000 \
0x100001234
Parameters:
-arch: Architecture (arm64, x86_64)-o: Path to dSYM or binary-l: Load address from crash logMultiple Addresses:
atos -arch arm64 -o MyApp.dSYM -l 0x100000000 \
0x100001234 0x100002345 0x100003456
Access: Xcode → Window → Organizer
Features:
Crashes Tab:
Set Breakpoint:
(lldb) breakpoint set --name ViewController.loginButtonTapped
(lldb) breakpoint set --file ViewController.swift --line 45
Examine Variables:
(lldb) po user
(lldb) p user?.name
(lldb) frame variable
Navigate Stack:
(lldb) bt # Print backtrace
(lldb) frame select 2 # Switch to frame 2
(lldb) up # Move up stack
(lldb) down # Move down stack
Memory Inspection:
(lldb) memory read 0x100001234
(lldb) register read
Workflow:
1. Build app (xcode-workflows)
2. Boot simulator (simulator-workflows → boot)
3. Install app (simulator-workflows → install)
4. Launch with lldb attached (Xcode → Debug)
5. Reproduce crash
6. Analyze in debugger
Retrieve Logs:
1. Crash occurs in simulator
2. Console.app → Filter by app name
3. Or: ls ~/Library/Logs/DiagnosticReports/ | grep MyApp
4. Read crash log
5. Symbolicate if needed
xc://reference/crash-types: Complete crash type referencexc://workflows/symbolication: Detailed symbolication guidexc://tools/debugging: LLDB and debugging tools referenceTip: Enable Address Sanitizer and Undefined Behavior Sanitizer in scheme diagnostics to catch memory issues early.