---
name: axiom-lldb
description: Use when ANY runtime debugging is needed — setting breakpoints, inspecting variables, evaluating expressions, analyzing threads, or reproducing crashes interactively with LLDB
license: MIT
---

# LLDB Debugging

Interactive debugging with LLDB. The debugger freezes time so you can interrogate your running app — inspect variables, evaluate expressions, navigate threads, and understand exactly why something went wrong.

**Core insight:** "LLDB is useless" really means "I don't know which command to use for Swift types." This is a knowledge-gap problem, not a tool problem.

## Red Flags — Check This Skill When

| Symptom | This Skill Applies |
|---------|-------------------|
| Need to inspect a variable at runtime | Yes — breakpoint + inspect |
| Crash you can reproduce locally | Yes — breakpoint before crash site |
| Wrong value at runtime but code looks correct | Yes — step through and inspect |
| Need to understand thread state during hang | Yes — pause + thread backtrace |
| `po` doesn't work / shows garbage | Yes — Playbook 3 has alternatives |
| Crash log analyzed, need to reproduce | Yes — set breakpoints from crash context |
| Need to test a fix without rebuilding | Yes — expression evaluation |
| Want to break on all exceptions | Yes — exception breakpoints |
| App feels slow but responsive | No — use axiom-performance-profiling |
| Memory grows over time | No — use axiom-memory-debugging first |
| App completely frozen | Maybe — use axiom-hang-diagnostics first, then LLDB for thread inspection |
| Crash in production, no local repro | No — use axiom-testflight-triage first |

## LLDB vs Other Tools

```dot
digraph tool_selection {
    "What do you need?" [shape=diamond];

    "axiom-testflight-triage" [shape=box];
    "axiom-hang-diagnostics" [shape=box];
    "axiom-memory-debugging" [shape=box];
    "axiom-performance-profiling" [shape=box];
    "LLDB (this skill)" [shape=box, style=bold];

    "What do you need?" -> "axiom-testflight-triage" [label="Crash log from field,\ncan't reproduce locally"];
    "What do you need?" -> "axiom-hang-diagnostics" [label="App frozen,\nneed diagnosis approach"];
    "What do you need?" -> "axiom-memory-debugging" [label="Memory growing,\nneed leak pattern"];
    "What do you need?" -> "axiom-performance-profiling" [label="Need to measure\nCPU/memory over time"];
    "What do you need?" -> "LLDB (this skill)" [label="Need to inspect state\nat a specific moment"];
}
```

**Rule of thumb:** Instruments *measures*. LLDB *inspects*. If you need to understand what's happening at a specific moment in time, use LLDB. If you need to understand trends over time, use Instruments.

## Response Format

When helping with LLDB debugging, structure your output as:

1. **Immediate diagnosis** (1-3 bullets, confidence-tagged: HIGH/MEDIUM/LOW)
2. **Commands to run** (numbered, copy-paste ready, with `(lldb)` prefix)
3. **What to look for** (command → expected output → interpretation)
4. **Likely root causes** (ranked by probability)
5. **Next breakpoint plan** (catch it earlier next time)
6. **If no debugger attached** (crash-log-only fallback path)

---

## Playbook 1: Crash Triage

**Goal:** Understand why the app crashed, starting from the stop point.

### Step 1: Read the Stop Reason

When the debugger stops, the first thing to check:

```
(lldb) thread info
```

This shows the stop reason. Common stop reasons:

| Stop Reason | Meaning | Next Step |
|-------------|---------|-----------|
| `EXC_BAD_ACCESS (SIGSEGV)` | Accessed invalid memory (null pointer, dangling reference) | Check the address — `0x0` to `0x10` = nil dereference |
| `EXC_BAD_ACCESS (SIGBUS)` | Misaligned or invalid address | Usually C interop or unsafe pointer issue |
| `EXC_BREAKPOINT (SIGTRAP)` | Hit a trap — Swift runtime check failed | Check for `fatalError()`, `preconditionFailure()`, force-unwrap of nil, array out of bounds |
| `EXC_CRASH (SIGABRT)` | Deliberate abort — assertion or uncaught exception | Look at "Application Specific Information" for the message |
| `breakpoint` | Your breakpoint was hit | Normal — inspect state |

### Step 2: Get the Backtrace

```
(lldb) bt
```

Read top-to-bottom. Find the first frame in YOUR code (not system frameworks). That's where to start investigating.

```
(lldb) bt 10
```

Limit to 10 frames if the full trace is noisy.

### Step 3: Navigate to Your Frame

```
(lldb) frame select 3
```

Jump to frame 3 (or whichever frame is in your code).

### Step 4: Inspect State

```
(lldb) v
(lldb) v self.someProperty
(lldb) v localVariable
```

Use `v` (not `po`) for reliable Swift value inspection. See Playbook 3 for details.

### Step 5: Classify and Fix

| Exception Type | Typical Cause | Fix Pattern |
|----------------|---------------|-------------|
| `EXC_BAD_ACCESS` at low address | Force-unwrap nil optional | `guard let` / `if let` |
| `EXC_BAD_ACCESS` at high address | Use-after-free / dangling pointer | Check object lifetime, `[weak self]` |
| `EXC_BREAKPOINT` | Swift runtime trap (bounds, unwrap, precondition) | Fix the violated precondition |
| `SIGABRT` | Uncaught ObjC exception or `fatalError()` | Read the exception message, fix the root cause |

### Step 6: Set a Conditional Breakpoint to Catch It Earlier

```
(lldb) breakpoint set -f MyFile.swift -l 42 -c "value == nil"
```

This breaks only when `value` is nil at line 42 — catches the problem before the crash.

---

## Playbook 2: Hang/Deadlock Diagnosis

**Goal:** Understand why the app is frozen by inspecting all thread states.

### Step 1: Pause the App

If the app is hung, press the pause button in Xcode (⌃⌘Y) or:

```
(lldb) process interrupt
```

### Step 2: Get All Thread Backtraces

```
(lldb) thread backtrace all
```

Or the shorthand:

```
(lldb) bt all
```

### Step 3: Classify Thread States

Look at Thread 0 (main thread) — it processes all UI events. If it's blocked, the app is frozen.

**Main thread blocked on synchronous wait:**
```
frame #0: libsystem_kernel.dylib`__psynch_mutexwait
frame #1: libsystem_pthread.dylib`_pthread_mutex_firstfit_lock_wait
...
frame #5: MyApp`ViewController.viewDidLoad()
```
Translation: Main thread is waiting for a mutex lock. Something else holds it.

**Main thread blocked on dispatch_sync:**
```
frame #0: libdispatch.dylib`_dispatch_sync_f_slow
...
frame #3: MyApp`DataManager.fetchData()
```
Translation: `DispatchQueue.main.sync` called from background → classic deadlock.

**Main thread busy (CPU-bound):**
```
frame #0: MyApp`ImageProcessor.processAllImages()
frame #1: MyApp`ViewController.viewDidLoad()
```
Translation: Expensive work on main thread. Move to background.

### Step 4: Check for Deadlocks

If two threads are both waiting on something the other holds:

```
(lldb) thread list
```

Look for multiple threads with state `waiting` that reference each other's locks.

### Step 5: Inspect Specific Thread

```
(lldb) thread select 3
(lldb) bt
(lldb) v
```

Switch to another thread to inspect its state.

**Cross-reference:** For fix patterns once you've identified the hang cause → `/skill axiom-hang-diagnostics`

---

## Playbook 3: Swift Value Inspection

**This is the core value of this skill.** Most developers abandon LLDB because `po` doesn't work reliably with Swift types. Here's what actually works.

### The Four Print Commands

| Command | Full Form | What It Does | Best For |
|---------|-----------|--------------|----------|
| `v` | `frame variable` | Reads memory directly, no compilation | Swift structs, enums, locals — **your default** |
| `p` | `expression` (with formatter) | Compiles expression, shows formatted result | Computed properties, function calls |
| `po` | `expression --object-description` | Calls `debugDescription` | Classes with `CustomDebugStringConvertible` |
| `expr` | `expression` | Evaluates arbitrary code | Calling methods, modifying state |

### When to Use Each

**Start with `v`** — it's fastest and most reliable for stored properties:

```
(lldb) v self.userName
(lldb) v self.items[0]
(lldb) v localStruct
```

`v` works by reading memory directly. It doesn't compile anything, so it can't fail due to expression compilation errors.

**`v` limitation:** It only reads stored properties — computed properties, `lazy var` (before first access), and property wrapper projected values (`$binding`) won't show meaningful values. If a field looks wrong or missing with `v`, try `p` instead.

**Use `p` when `v` can't reach it:**

```
(lldb) p self.computedProperty
(lldb) p self.items.count
(lldb) p someFunction()
```

`p` compiles and executes the expression. Needed for computed properties and function calls.

**Use `po` for class descriptions:**

```
(lldb) po myObject
(lldb) po error
(lldb) po notification
```

`po` calls `debugDescription` on the result. Best for objects that have meaningful descriptions (NSError, Notification, etc.).

### The "LLDB Is Broken" Moments

| What You See | Why | Fix |
|--------------|-----|-----|
| `<uninitialized>` | `po` failed; variable hasn't been populated by optimizer | Use `v` instead |
| `expression failed to parse, unknown type name` | Swift expression parser can't resolve the type | Try `expr -l objc -- (id)0x12345` for ObjC objects, or use `v` |
| `<variable not available>` | Compiler optimized it out (Release build) | Rebuild with Debug, per-file `-Onone`, or `register read` as last resort |
| `error: Couldn't apply expression side effects` | Expression had side effects LLDB couldn't reverse | Try a simpler expression; avoid mutating state |
| `po` shows memory address instead of value | Object doesn't conform to `CustomDebugStringConvertible` | Use `v` for raw value, or implement the protocol |
| `cannot find 'self' in scope` | Breakpoint is in a context without `self` (static, closure) | Use `v` with the explicit variable name |
| `p` shows `$R0 = ...` but `po` crashes | Different compilation paths | Use `p` when it works; `po` adds an extra description step that can fail |

### Inspecting Optionals

```
(lldb) v optionalValue
```
Shows: `(String?) some = "hello"` or `(String?) none`

Don't use `po optionalValue` — it may show just `Optional("hello")` which is less useful.

### Inspecting Collections

```
(lldb) v myArray
(lldb) v myArray[2]
(lldb) v myDict
```

For large collections, limit output:

```
(lldb) p Array(myArray.prefix(5))
```

### Inspecting SwiftUI State

SwiftUI `@State` is backed by stored properties with underscore prefix:

```
(lldb) v self._isPresented
(lldb) v self._items
```

For `@Observable` models:

```
(lldb) v self.viewModel.propertyName
```

**Diagnosing "view doesn't update":** If a property changes (confirmed with `v`) but the SwiftUI view doesn't re-render, check which thread the mutation happens on with `bt`. `@Observable` mutations must happen on `@MainActor` for SwiftUI to observe them — mutations on a background actor won't trigger view updates. Use `Self._printChanges()` inside a view body to see which property triggered (or didn't trigger) a re-render:

```
(lldb) expr Self._printChanges()
```

For the full observation diagnostic tree → `/skill axiom-swiftui-debugging`

### Inspecting Actors

Actor state is best inspected with `v`, which reads memory directly without isolation concerns:

```
(lldb) v actor
```

Shows all stored properties. This works because LLDB pauses the entire process — you can read any memory regardless of actor isolation (which is a compile-time concept).

### Modifying Values at Runtime

```
(lldb) expr self.debugFlag = true
(lldb) expr myArray.append("test")
(lldb) expr self.view.backgroundColor = UIColor.red
```

Modify values without rebuilding. Useful for testing theories.

### Referencing Previous Results

LLDB assigns result variables (`$R0`, `$R1`, etc.):

```
(lldb) p someValue
$R0 = 42
(lldb) p $R0 + 10
$R1 = 52
```

---

## Playbook 4: Breakpoint Strategies

### Source Breakpoints (Basic)

```
(lldb) breakpoint set -f ViewController.swift -l 42
(lldb) b ViewController.swift:42
```

Short form `b` works for simple cases.

### Conditional Breakpoints

Break only when a condition is true:

```
(lldb) breakpoint set -f MyFile.swift -l 42 -c "index > 100"
(lldb) breakpoint set -f MyFile.swift -l 42 -c "name == \"test\""
```

**Iteration-based:** Break after N hits:

```
(lldb) breakpoint set -f MyFile.swift -l 42 -i 50
```

Ignores the first 50 hits, then breaks.

### Logpoints (Action + Auto-Continue)

Log without stopping — like a print statement but no rebuild needed:

```
(lldb) breakpoint set -f MyFile.swift -l 42
(lldb) breakpoint command add 1
> v self.value
> continue
> DONE
```

Or in Xcode: Edit breakpoint → Add Action → "Log Message" → use `@self.value@` token syntax → Check "Automatically continue"

### Symbolic Breakpoints

Break on ANY call to a method by name:

```
(lldb) breakpoint set -n viewDidLoad
(lldb) breakpoint set -n "MyClass.myMethod"
```

Break on all ObjC messages to a selector:

```
(lldb) breakpoint set -S "layoutSubviews"
```

### Exception Breakpoints

**Swift errors (break on throw):**
```
(lldb) breakpoint set -E swift
```

**Objective-C exceptions (break on throw):**
```
(lldb) breakpoint set -E objc
```

**In Xcode:** Breakpoint Navigator → + → Swift Error Breakpoint / Exception Breakpoint

This is the single most useful breakpoint for crash debugging. It stops at the throw site instead of the catch/crash site.

### Watchpoints

Break when a variable's value changes:

```
(lldb) watchpoint set variable self.count
(lldb) watchpoint set variable -w read_write myGlobal
```

Watchpoints are hardware-backed — limited to ~4 per process but very fast.

### One-Shot Breakpoints

Break once, then auto-delete:

```
(lldb) breakpoint set -f MyFile.swift -l 42 -o
```

### Managing Breakpoints

```
(lldb) breakpoint list
(lldb) breakpoint disable 3
(lldb) breakpoint enable 3
(lldb) breakpoint delete 3
(lldb) breakpoint delete
```

---

## Playbook 5: Async/Concurrency Debugging

### Identifying Async Frames

Swift concurrency backtraces are noisy — expect `swift_task_switch`, `_dispatch_call_block_and_release`, and executor internals mixed in with your code. Don't be discouraged by 40+ frames of runtime noise. Focus on frames from YOUR module.

In Swift concurrency backtraces, look for `swift-task` frames:

```
Thread 3:
frame #0: MyApp`MyActor.doWork()
frame #1: swift_task_switch
frame #2: MyApp`closure #1 in ViewController.loadData()
```

The `swift_task_switch` frame indicates an async suspension point. Your code frames are the ones prefixed with your module name (`MyApp` above).

### Inspecting Task State

```
(lldb) thread backtrace all
```

Look for threads with `swift_task` in their frames. Each represents an active Swift task.

### Actor-Isolated Code

When stopped inside an actor:

```
(lldb) v self
```

Shows all actor state. This works because LLDB pauses the entire process — actor isolation is a compile-time concept, not a runtime lock (for default actors).

### Task Group Inspection

When debugging task groups, break inside the group closure and inspect:

```
(lldb) v
(lldb) bt
```

Each child task runs on its own thread. Use `bt all` to see them.

**Cross-reference:** For Swift concurrency patterns and fix strategies → `/skill axiom-swift-concurrency`. For profiling async performance → `/skill axiom-concurrency-profiling`

---

## Pressure Scenarios

### Scenario 1: "Release-Only Crash — LLDB Is Useless in Release"

**Situation:** Crash happens in Release builds but not Debug. Team says "we can't debug it."

**Why this fails:** Release optimizations change timing, memory layout, and can eliminate variables — making the crash non-reproducible in Debug.

**Correct approach:**

1. Build with Debug configuration but Release-like settings:
   - Optimization Level: `-O` (not `-Onone`)
   - Still include debug symbols (`DEBUG_INFORMATION_FORMAT = dwarf-with-dsym`)
2. Enable Address Sanitizer (`-fsanitize=address`) — catches memory errors with 2-3x overhead
3. Use the crash report to set breakpoints at the crash site
4. Set exception breakpoints to catch the error before the crash:
   ```
   (lldb) breakpoint set -E swift
   (lldb) breakpoint set -E objc
   ```
5. If variable shows `<optimized out>`, reduce optimization for that one file:
   - Build Settings → Per-file flags → `-Onone` for the specific file
6. Last resort — read register values directly (variables live in registers before being optimized out):
   ```
   (lldb) register read
   (lldb) register read x0 x1 x2
   ```
   On ARM64: `x0` = self, `x1`-`x7` = first 7 arguments. Check `/skill axiom-lldb-ref` Part 1 for details.

### Scenario 2: "Just Add Print Statements"

**Situation:** Developer adds `print()` calls to debug, rebuilds, runs, reads console. Repeat.

**Why this fails:** Each print-debug cycle costs 3-5 minutes (edit → build → run → navigate to state → read output). An LLDB breakpoint costs 30 seconds.

**Correct approach:**

1. Set a breakpoint at the line you'd add a `print()`:
   ```
   (lldb) b MyFile.swift:42
   ```
2. Add a logpoint for "print-like" behavior without rebuilding:
   - Edit breakpoint → Add Action → Log Message → Check "Auto continue"
3. Inspect variables directly: `v self.someValue`
4. Modify variables at runtime to test theories: `expr self.debugMode = true`
5. **One breakpoint session replaces 5-10 print-debug cycles.**

**Time comparison** (typical control-flow debugging):
| Approach | Per investigation | 5 variables |
|----------|-------------------|-------------|
| print() statements | 3-5 min (build + run) | 15-25 min |
| LLDB breakpoint | 30 sec (set + inspect) | 2.5 min |

**Exception:** In tight loops (thousands of hits/sec), logpoints add per-hit overhead. Use `-i` to skip to the iteration you care about, or use a temporary `print()` for that specific loop.

### Scenario 3: "po Doesn't Work So LLDB Is Broken"

**Situation:** Developer types `po myStruct` and gets garbage. Concludes LLDB is broken for Swift. Goes back to print debugging.

**This is the #1 reason developers abandon LLDB.**

**Why `po` fails with Swift structs:** `po` calls `debugDescription` which requires compiling an expression in the debugger context. For Swift structs, this compilation often fails due to missing type metadata, generics, or module resolution issues.

**Correct approach:**

1. Use `v` instead of `po` — reads memory directly, no compilation:
   ```
   (lldb) v myStruct
   (lldb) v myStruct.propertyName
   ```
2. Use `p` for computed properties:
   ```
   (lldb) p myStruct.computedValue
   ```
3. Use `po` only for classes with `CustomDebugStringConvertible`
4. If `p` also fails, try specifying the language:
   ```
   (lldb) expr -l objc -- (id)0x12345
   ```
5. If everything fails, `v self` always works inside a method.

---

## Anti-Patterns

| Anti-Pattern | Why It's Wrong | Better Alternative |
|---|---|---|
| `po` everything | Fails for Swift structs, enums, optionals | `v` for values, `po` only for classes |
| Print-debug cycles | 3-5 min per cycle vs 30 sec breakpoint | Breakpoints with logpoint actions |
| "LLDB doesn't work with Swift" | It does — wrong command choice | `v` is designed for Swift values |
| Ignoring backtraces | Jumping to guesses instead of reading the trace | `bt` first, then navigate frames |
| Conditional breakpoints on every hit | Slows execution if condition is expensive | Use `-i` (ignore count) when possible |
| Debugging optimized (Release) builds | Variables missing, code reordered | Debug configuration, or per-file `-Onone` |
| Force-continuing past exceptions | Hides the real error | Fix the exception, don't suppress it |
| No exception breakpoints set | Crashes land in system code, not throw site | Always add Swift Error + ObjC Exception breakpoints |

## Debugging Checklist

Before starting a debug session:

- [ ] Debug build configuration (not Release)
- [ ] Exception breakpoints enabled (Swift Error + ObjC Exception)
- [ ] Breakpoint set before suspected problem area
- [ ] Know which command to use: `v` for values, `p` for computed, `po` for descriptions

During debug session:

- [ ] Read stop reason (`thread info`) before anything else
- [ ] Get backtrace (`bt`) — find your frame
- [ ] Navigate to your frame (`frame select N`)
- [ ] Inspect relevant state (`v self`, `v localVar`)
- [ ] Understand the cause before writing any fix

After finding the issue:

- [ ] Set conditional breakpoint to catch recurrence
- [ ] Consider adding assertion/precondition for this case
- [ ] Remove temporary breakpoints

## Resources

**WWDC**: 2019-429, 2018-412, 2022-110370

**Docs**: /xcode/stepping-through-code-and-inspecting-variables-to-isolate-bugs, /xcode/setting-breakpoints-to-pause-your-running-app, /xcode/diagnosing-memory-thread-and-crash-issues-early

**Skills**: axiom-lldb-ref, axiom-testflight-triage, axiom-hang-diagnostics, axiom-memory-debugging, axiom-swift-concurrency, axiom-concurrency-profiling