iOS Debugging & Crash Investigation

Use this guide when diagnosing runtime crashes, render errors, or unexpected behavior.

MCP Tool Selection — Check What's Available

At the start of a debugging session, check which MCP servers are loaded. Use ToolSearch to probe:

ToolSearch("XcodeBuildMCP")   → if found: full LLDB + simulator + build
ToolSearch("mcp__xcode__")    → if found: build + preview + test (no LLDB)

Priority order:

1. Apple Xcode MCP (mcp__xcode__*) — use for build, preview, test, issues, build log
2. XcodeBuildMCP (mcp__XcodeBuildMCP__*) — use ONLY for what Apple Xcode MCP cannot do: LLDB debugging, simulator log capture, screenshots, UI snapshots, video recording

What Apple Xcode MCP handles (prefer these when available):

What ONLY XcodeBuildMCP can do (fallback to these):

Install XcodeBuildMCP: claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

LLDB Crash Debugging Workflow (XcodeBuildMCP required)

1. Build & run:    mcp__XcodeBuildMCP__simulator__build_and_run
2. Set breakpoint: mcp__XcodeBuildMCP__debugging__add_breakpoint
3. When paused:    mcp__XcodeBuildMCP__debugging__stack          → backtrace
4. Inspect vars:   mcp__XcodeBuildMCP__debugging__variables      → local state
5. Run LLDB:       mcp__XcodeBuildMCP__debugging__lldb_command   → "po myVariable"
6. Continue:       mcp__XcodeBuildMCP__debugging__continue
7. Detach:         mcp__XcodeBuildMCP__debugging__detach

IMPORTANT: XcodeBuildMCP manages its OWN debug session. Do NOT run the app from Xcode at the same time — only one debugger can attach. Use build_and_run from XcodeBuildMCP, then attach.

Decision Logic

Crash Investigation Methodology

Step 1: Get the Backtrace (FIRST thing to do)

If XcodeBuildMCP is available:

→ mcp__XcodeBuildMCP__debugging__stack

This gives the full backtrace from all threads. Find the crashing thread.

If only Apple Xcode MCP: ask the user to copy the backtrace from Xcode's Debug Navigator.

Step 2: Find the First App Frame

Read the stack from bottom to top. The first frame in YOUR code (not Apple/system frames) is the root cause.

Step 3: Inspect State

→ mcp__XcodeBuildMCP__debugging__variables    (local vars)
→ mcp__XcodeBuildMCP__debugging__lldb_command  "po self"
→ mcp__XcodeBuildMCP__debugging__lldb_command  "po someProperty"

Step 4: Set Breakpoints for Next Run

→ mcp__XcodeBuildMCP__debugging__add_breakpoint  file:line or function name
→ mcp__XcodeBuildMCP__debugging__continue

Step 5: Fix and Re-run

Edit the code, rebuild:

→ mcp__xcode__BuildProject                         (preferred — uses Xcode)
→ mcp__XcodeBuildMCP__simulator__build_and_run      (fallback — standalone)

Known Crash Patterns

AsyncRenderer Color Crash (CRITICAL)

See reference/async-renderer-crash.md for the full investigation.

Pattern: EXC_BREAKPOINT on com.apple.SwiftUI.AsyncRenderer with _dispatch_assert_queue_fail Cause: UIKit dynamic color providers (UIColor { traits in ... }) resolved off main queue Fix: Use static Color(hex:) instead of Color(light:dark:) with UIColor provider

Swift 6 Concurrency Violations

Pattern: EXC_BREAKPOINT with _swift_task_checkIsolatedSwift Cause: @MainActor-isolated code accessed from non-isolated context Fix: Ensure all UI-bound state is @MainActor. Snapshot values before crossing isolation boundaries.

AVFoundation on Simulator

Pattern: Crash in AVAudioSession or AVAudioRecorder init Cause: Deprecated APIs (e.g., requestRecordPermission callback-based), simulator audio routing issues, @Sendable Timer closures capturing @MainActor state Fix: Use AVAudioApplication.requestRecordPermission() (iOS 17+ async). Use Task loops instead of Timer.scheduledTimer for metering. Guard recorder.record() return value.

SwiftData Thread Safety

Pattern: Crash on ModelContext access from background thread Cause: ModelContext is not Sendable Fix: Use @ModelActor for background contexts, @MainActor for UI contexts.

ForEach Identity Crash

Pattern: Index out of bounds during list mutation Cause: Using .indices or unstable identity with ForEach Fix: Use Identifiable conformance or stable id: keypath.

Xcode Debugging Tools (Manual)

Breakpoints

• Exception Breakpoint: Catches all runtime exceptions
• Symbolic Breakpoint: _dispatch_assert_queue_fail — catches queue violations
• Swift Error Breakpoint: Catches all thrown Swift errors

Runtime Sanitizers (Scheme → Diagnostics)

Always enable Main Thread Checker.

Console Logging

import OSLog
let logger = Logger(subsystem: "com.example.app", category: "debugging")
logger.debug("State: \(String(describing: newValue))")

CLI Debugging

# Launch with console output
xcrun simctl launch --console booted com.example.app

# Find crash logs
find ~/Library/Logs/DiagnosticReports -name "<AppName>*" -type f

# Symbolicate
atos -arch arm64 -o <AppName>.app/<AppName> -l 0x100000000 0x100012345

Rules

• Always get the backtrace first — don't guess
• Check the crashing thread, not Thread 1
• Trust the first app frame in the stack
• Use OSLog (not print()) for debugging
• XcodeBuildMCP owns the debug session — don't also run from Xcode