Drive LLDB and Xcode to find the cause of a bug fast: stop in the right place, look at real state, change it live, and prove a fix before touching the code. Rebuilding is the last resort, not the first move. Once the live experiment confirms the cause, fix the source and verify it in a clean run without the injected behavior.
Debugging loop: run, break, inspect, change, repeat. Every reference below serves one step of that loop.
Debugging process:
- Reproduce and get a debugger on the process (Xcode run, Run Without Building, attach by name or PID, batch
lldbfrom a terminal) usingreferences/attaching-and-running.md. - Learn or refresh LLDB's command grammar, print commands, language contexts, and
$variables usingreferences/fundamentals.md. - Stop in the right place with the right kind of breakpoint (line, column, symbolic, regex, conditional, one-shot, dependent, exception, Swift error, runtime issue) using
references/breakpoints.md. - Inspect state: variables, objects by raw address, registers and
$arg1in assembly frames, backtraces, threads, images, memory, usingreferences/inspecting-state.md. - Move through code: step, finish,
thread return,thread jump, drag the instruction pointer, run functions with breakpoints honored, usingreferences/flow-control.md. - Change state and inject code without rebuilding: mutate values, call methods, auto-continuing breakpoint actions, replace a line, stub a function, flush Core Animation, using
references/modifying-runtime-state.md. - For UI bugs (scene and window selection, layout, hit testing, keyboard focus, dark mode, animations, SwiftUI re-renders) use
references/view-debugging.md. - For "who wrote this value" and memory problems (watchpoints, memory graph, malloc history, leaks, vmmap, zombies, sanitizers, jetsam) use
references/watchpoints-and-memory.md. - For crash logs, dSYMs, UUIDs,
atos, source maps, core files, and the meaning of exception types usereferences/crashes-and-symbolication.md. - When
poorpfail in Swift, types are missing, or variables are optimized out, usereferences/swift-debugging.md. - For code without source: identify the binary and slice, translate addresses, find inherited Objective-C implementations, read Mach-O structure, using
references/debugging-without-source.md. For registers, calling conventions, arm64 instructions, stack frames, and DWARF locations usereferences/assembly-and-abi.md. - For blocks, class dumps per image, stripped Objective-C stacks, heap instances, singleton storage, cross-references, and Simulator system processes use
references/runtime-memory.md. - To load a diagnostic library, interpose a C call, swizzle an Objective-C method in your own app, or forward a Simulator launch environment use
references/dynamic-loading-and-interposition.md. - When attach fails, a library is rejected, or the app exits under a debugger (signing, entitlements, hardened runtime,
PT_DENY_ATTACH) usereferences/signing-and-attach-diagnostics.md. - When you type the same command twice, persist it: aliases, regex commands, Python commands, data formatters,
.lldbinitlayout, third-party command packages, usingreferences/custom-commands.md. For structuredSBValuework, allocation histories, and the bundled helper commands usereferences/advanced-python.md. - To trace a whole process or Apple's code without source (DTrace, breakpoint tracers, stop hooks, unified logging, hang sampling) use
references/tracing-and-dtrace.md. For recursion-aware timing, syscall arguments, and destructive DTrace actions usereferences/advanced-dtrace.md. - For remote
debugserversessions,lldb-dap, LLDB's MCP server, custom breakpoint resolvers, and scripted processes or thread plans usereferences/remote-and-tooling.md. - For step-by-step recipes for the most common situations use
references/playbooks.md. - Before reporting, check
references/anti-patterns.mdfor the mistakes that waste the most time.
If doing partial work, load only the relevant reference files.
Two ways to work
You hold the debugger. You have a terminal, the app runs in the Simulator or on the Mac, and you can attach with xcrun lldb. Do it yourself: attach, run the commands, read the output, detach. A finite snapshot is a batch call; a trace that waits for the user is a batch call with an in-LLDB deadline. See "Driving LLDB from a terminal or an agent" in references/attaching-and-running.md. If Xcode already debugs the process, do not attach a second debugger: work through the user's console instead.
The user holds the debugger. The app runs in Xcode on their machine or device. Give exact console commands one at a time, say what output to expect, and keep their session alive: never ask for a rebuild to test a hypothesis that a breakpoint action or an expression can test now.
In both modes the deliverable is the same: what you observed, what it proves, the fix, and how it was verified live and then in a clean run.
Task-based routing
Match the user's situation to the read order. Load only what you need.
"Something is wrong on screen, I don't want to rebuild"
references/attaching-and-running.md- attach to the running app or Run Without Buildingreferences/view-debugging.md- select the scene's window, find the view, copy its pointer, inspect constraintsreferences/modifying-runtime-state.md- mutate, flush, verify, then port the fix to code
"I want to test a one-line fix live"
references/modifying-runtime-state.md- auto-continuing breakpoint with anexpressionaction,thread jump+expressionto replace a linereferences/breakpoints.md- conditions and actions in Xcode and on the console
"Who changes this property / label / variable?"
references/breakpoints.md- symbolic breakpoint on the setter,po $arg1at entry, dependent one-shot breakpointsreferences/watchpoints-and-memory.md- watchpoint when no setter is involved (inout, direct writes)
"A tap or gesture does nothing" / "focus jumps to the wrong field"
references/view-debugging.md- the hit-testing checklist,sendEvent:tracer, responder chain, target-action lookup,becomeFirstRespondertracingreferences/playbooks.md- the full recipe
"po fails / the variables view is empty / types are missing"
references/swift-debugging.md-vfirst,swift-healthcheck, module and dSYM problems, source maps, optimized codereferences/fundamentals.md- language contexts and$variables
"I have a crash log"
references/crashes-and-symbolication.md- open it in Xcode against the project,atos, UUID matching, exception typesreferences/breakpoints.md- exception and Swift error breakpoints to catch it live
"Memory is too high / the app gets killed"
references/watchpoints-and-memory.md- footprint model, memory graph,vmmap,heap,leaks,malloc_history, jetsam reportsreferences/advanced-python.md- allocation stack logging and its limits
"The app hangs"
references/tracing-and-dtrace.md- sample first, compare repeated stacksreferences/playbooks.md- the hang recipe, then targeted LLDB inspection
"I have no source for this code"
references/debugging-without-source.md- loaded image, slice, UUID, address spaces, runtime method lookupreferences/assembly-and-abi.md- arguments and returns per ABI, arm64 instructions, framesreferences/breakpoints.md- symbolic and regex breakpoints scoped to a modulereferences/runtime-memory.md- class dumps, stripped stacks, blocks, heap instances, singletonsreferences/tracing-and-dtrace.md- trace every method of a class with a breakpoint tracer or DTrace
"I need to hook this call in my app"
references/dynamic-loading-and-interposition.md- pick the mechanism, then thedlopen, interposing, or saved-IMP recipereferences/signing-and-attach-diagnostics.md- when the library is not loaded or is rejected
"Attach is denied / the app quits as soon as the debugger is on"
references/signing-and-attach-diagnostics.md- diagnose the failing layer, inspect signatures, own-app anti-debug checksreferences/attaching-and-running.md- prerequisites and Developer Mode
"Make this repeatable" (aliases, scripts, formatters)
references/custom-commands.md-.lldbinit,command alias,command regex, Python commands,type summaryreferences/advanced-python.md-SBValuediscipline, expression ownership, the bundledadb-*commands
"Drive the debugger for me from the terminal"
references/attaching-and-running.md- batch mode, command files, deadlines, detach and ownership rules
"Debug over the network, from an editor, or through MCP"
references/remote-and-tooling.md-debugserver,lldb-dap,protocol-server start MCP, resolvers, scripted processes
Decision trees
Which print command?
Need to see a variable or a field of it, in Swift?
-> v <expr> (frame variable: no compile, dynamic types resolved per step)
Need to evaluate an expression, call a method, or compute something?
-> p <expr> (dwim-print since Xcode 15: tries frame variable, then expression)
Need the object's own description (debugDescription / description)?
-> po <expr> (runs description code: avoid it in deadlock or lifetime investigations)
Stopped in Swift but holding a raw address of a live Objective-C object?
-> expression -l objc -O -- (id)0x... (alias it as cpo; the cast does not validate the pointer)
Must not run any target code (corruption, locks, lifetime)?
-> frame variable -d no-run-target -R <expr>
Expression fails with type or module errors?
-> v first, then swift-healthcheck, then references/swift-debugging.md
Which way to stop?
Know the file and line? -> line breakpoint; column breakpoint for closures on one line
Know the symbol but not the file? -> symbolic breakpoint (-n), scope with --shlib
Know only a pattern (Swift mangling)? -> rb <regex> [-s Module], find it first with image lookup -rn
Need the arguments in registers? -> add -K false to stop before the prologue
Fires too often? -> condition (-c), ignore count (-i), one-shot (--one-shot true),
dependent one-shot breakpoint armed from an auto-continue action,
or raise(SIGSTOP) in code for million-hit loops
Value changes, no setter called? -> watchpoint
Uncaught NSException or C++ throw? -> Exception breakpoint (po $arg1 at objc_exception_throw)
Swift throw? -> Swift Error breakpoint (also stops on throws that get caught)
Main thread / layout / sanitizer issue? -> Runtime Issue breakpoint (enable the checker in the scheme)
Only need a log, not a stop? -> breakpoint action + auto-continue (-C "..." -G1)
Who changed this value?
Setter exists and is called? -> symbolic breakpoint on the setter, po $arg1 at entry / bt
Swift property? -> rb Module.Type.prop.setter
Written through inout or raw ptr? -> watchpoint on the field address, sized to the field
Singleton set up somewhere? -> watchpoint on the static pointer storage, before first access
Object created where? -> Malloc Stack Logging + malloc_history / memory graph creation backtrace
Rebuild or not?
Change a constant, color, frame, flag? -> expression + CATransaction flush, no rebuild
Add a missing call or line? -> auto-continuing breakpoint with expression action
Skip or replace a line? -> check disassembly, then thread jump --by 1 + expression
Stub a function's return? -> breakpoint at entry, thread return <value>, auto-continue
(simple synchronous functions only)
Observe a C call or method without source? -> breakpoint action first; interpose or swizzle in a lab build
Hypothesis confirmed live? -> now edit the code, delete the injecting breakpoints, rebuild
Hot path hit millions of times? -> rebuild with an if + raise(SIGSTOP)
No source: where to start?
Which binary and slice? -> image list -o -f, file / lipo -archs, dwarfdump --uuid
Which symbol? -> image lookup -rn 'pattern' Module
Objective-C method, no symbol? -> class_getInstanceMethod + method_getImplementation, break on the IMP
Arguments? -> stop with -K false, read registers per ABI (references/assembly-and-abi.md)
Who calls it? -> bt, then disassemble the caller frame
Every method of a class? -> rb tracer with -G1, or DTrace objc provider
Where does a repeated command live?
Static text, maybe %1 arguments? -> command alias (in ~/.lldbinit)
Needs regex dispatch on input? -> command regex (chain patterns, catch-all last)
Needs logic, options, output? -> Python command via command script import
Needs to change how a type prints? -> type summary add (string, or Python), @DebugDescription in Swift 6
Core Instructions
- Prefer the live process over a rebuild. Tweak values, inject the missing line, stub the return, and confirm the hypothesis in the running app. Edit source only after the debugger proved the fix, then delete every injecting breakpoint before the next run so the fix does not execute twice, and verify once more in a clean run.
- In Swift, reach for
vfirst. It reads memory with debug info and never compiles. Usepfor expressions andpoonly when you need the object's description. Descriptions run code: they can take locks or change state. - Know the language context. It comes from the selected frame: Swift code gives Swift, anything else gives Objective-C++. Pausing usually lands in a system frame, so it is Objective-C even in a pure Swift app. A raw address like
0x7f...is an integer in Swift: useexpression -l objc -O -- (id)0x...(aliascpo) for a live Objective-C object, orunsafeBitCast(0x..., to: T.self)when you know the type. Neither validates the pointer. - Persistent debugger variables start with
$(e let $vc = ...,e id $view = (id)0x...). Results are auto-named$R0,$R1,$0. They do not cross language contexts, they keep objects alive (mind that in a leak hunt), and their addresses mean nothing after a relaunch. - Put
--before arguments that start with-. Use backticks to splice a frame value into another context, and cast the spliced pointer:expression -l objc -O -- [(id)self.viewrecursiveDescription]. - Capital
-Cis a breakpoint command, lowercase-cis a condition.-G1auto-continues.--one-shot true(or-o 1) makes a breakpoint one-shot; the option takes a Boolean. - A symbolic breakpoint on a method the class does not override never resolves. Break on the implementing superclass and add a class condition, or resolve the inherited IMP through the runtime and break on its address.
- At an Objective-C method entry,
$arg1is the receiver,$arg2the selector (cast with(SEL)),$arg3the first integer or pointer parameter. Stop before the prologue (-K false) so the registers still hold them. Floating-point arguments use their own registers, Swift native calls use their own convention, and$arg1is not the return value: afterfinish, readx0on arm64 orraxon x86_64. - In UIKit, select the window of the scene that shows the bug:
UIApplication.keyWindowis deprecated and can belong to another scene or be nil. Store it once as$window(seereferences/view-debugging.md). - After mutating UI from the console, flush Core Animation:
e CATransaction.flush()in Swift,e (void)[CATransaction flush]in Objective-C. The render server is a separate process and keeps running while you are paused. Make UIKit calls on the main thread; find it withthread list, it is not always thread 1. thread jumponly moves the program counter. One source line can hold initialization, a release, or cleanup. Read the disassembly first, jump forward one line at a time, never across anawait, and preferthread returnor a breakpoint action when you can.- Hot breakpoints slow the app even when they do not stop. Use conditions and ignore counts for hundreds of hits, a dependent one-shot breakpoint for "only after X", and for millions of hits recompile with
if condition { raise(SIGSTOP) }. - Hardware watchpoints are few (often four on Apple silicon) and each covers a small aligned range;
watchpoint listshows the resources. Watch the exact field size (aBoolis 1 byte). Always pass the ID towatchpoint modify, and clear a condition withwatchpoint modify -c "" <id>. - A crash log is only useful with the matching dSYM: compare the UUID in Binary Images with
dwarfdump --uuid. Open the log in Xcode against the project before reaching foratos -i. A report has no heap: neverpoits addresses. - Inside Python scripts, use the five-argument command signature and its
exe_ctx, or theframea breakpoint callback receives. Never uselldb.frame,lldb.target, orlldb.process; they are REPL conveniences and go stale mid-script. Report throughresult.SetErrorandresult.AppendMessage. - DTrace runs on macOS and on Simulator processes from the host, with
sudo. SIP restricts some providers and protected targets. Always list probes with-lbefore adding an action so you know how many will fire, and report a permission failure instead of disabling SIP. - When you drive LLDB yourself, use
xcrun lldb --batch. The first failing-ocommand ends the batch, so put a read-only snapshot in a command file run withcommand source -e false. Acontinuethat may never stop needs a deadline inside LLDB: a Python timer that callsSendAsyncInterrupt(), followed bybreakpoint delete -fandprocess detach. Killing LLDB from outside loses the trace output. When LLDB exits, an attached process is detached and keeps running, and a process LLDB launched is killed. Never leave a process stopped when you are done. - Interposing, swizzling,
dlopen, patching an anti-debug check, and destructive DTrace are debugging tools for your own app or a disposable lab. Record what you changed, restore it, and relaunch clean before you trust the result. Disabling SIP, re-signing, or changing a global launch environment is a separate step: ask first. - Report what the debugger showed, not what you assumed. A hypothesis is confirmed when the live process behaves differently after your injected change. If nothing changes, the theory is wrong or the change hit the wrong object, thread, or moment: find out which before moving on.
Output Format
When you drove the debugger, report in this order:
- Observed: the exact state you saw (values, backtrace frames, view addresses), quoted from the console.
- Cause: the single sentence that explains the bug.
- Verified live: what you changed in the running process and what happened.
- Code fix: the diff to apply, plus "delete these breakpoints before rerunning" if any inject code.
- Clean run: the result after the fix without injected behavior, and whether you detached, resumed, or left the user's session as it was.
When the user drives Xcode, give a numbered list of actions. Each step is one console command or one click, followed by what they should see. Keep Objective-C and Swift contexts explicit in each command. Example:
- Pause the app, then in the console run
expression -l objc -O -- [[UIApplication sharedApplication] connectedScenes]and copy the address of the foreground-activeUIWindowScene. Thenexpression -l objc -O -- [(UIWindowScene *)0x600003b0c000 windows]andexpression -l objc -- UIWindow *$window = (UIWindow *)0x600003a08100with the window that shows the login screen. expression -l objc -O -- [$window recursiveDescription]. Find theUIButtonwhose frame width is wrong and copy its address.e -l objc -O -- (id)0x600003a1c2e0to confirm it is the right button.e -l objc -- (void)[(UIView *)0x600003a1c2e0 setBackgroundColor:[UIColor redColor]]thene -l objc -- (void)[CATransaction flush]. The button turns red in the Simulator while still paused.- Now the fix:
e -l objc -- (void)[(NSLayoutConstraint *)0x600002d11f00 setConstant:328]and flush again. The layout matches the design, so change the constant inLoginViewController.swiftand rebuild.
End of example.
References
references/fundamentals.md- how LLDB works, command grammar, help, print commands (v,p,po,expression), language contexts,$variables, formats, settings, Xcode UI to LLDB mapping.references/attaching-and-running.md- Run Without Building, attach by name/PID/wait-for, stdout trade-off, launch arguments, environment, I/O and signals, scheme diagnostics, per-project.lldbinit, driving LLDB in batch mode from a terminal or an agent.references/breakpoints.md- every breakpoint kind, Xcode breakpoint editor fields, conditions, actions, auto-continue, one-shot and dependent breakpoints, names, unresolved breakpoint diagnosis, stop hooks,breakpoint write/read.references/inspecting-state.md- frames, threads, variables, raw addresses, registers and calling conventions,image lookup, memory and disassembly, Objective-C runtime introspection.references/flow-control.md- stepping,step -a0,thread until,thread return,thread jump, dragging the PC, stepping one thread,expression -i0.references/modifying-runtime-state.md- mutate values, call methods, declare variables and functions in the debugger, inject fixes with breakpoint actions, replace a line, stub a function, flush Core Animation, prototype layout.references/view-debugging.md- scene and window selection, Xcode view debugger techniques, console equivalents, Auto Layout diagnosis, hit testing, keyboard focus, target-action, animations, appearance overrides, SwiftUI notes.references/watchpoints-and-memory.md- watchpoints, memory graph, Malloc Stack Logging,vmmap/heap/leaks/malloc_history, zombies, sanitizers,memory history, jetsam.references/crashes-and-symbolication.md- crash log anatomy, dSYM and UUID matching,atos, ASLR slide,crashlog, core files, source maps, exception types, catching exceptions live.references/swift-debugging.md- whypofails whilevworks,swift-healthcheck, modules and dSYMs, optimized code, type names and mangling,@DebugDescription, concurrency and SwiftUI specifics.references/debugging-without-source.md- binary and slice identification, runtime versus unslid versus file-offset addresses, inherited Objective-C implementations, Mach-O load commands and bindings, shared cache, disassembler workflows.references/assembly-and-abi.md- arm64 and x86_64 argument and return registers, Objective-C and Swift differences, arm64 instruction patterns, stack frames, DWARF locations, pointer authentication limits.references/runtime-memory.md- classes and methods per image, stripped Objective-C backtraces, block layout, heap instances, singleton storage, cross-references, Simulator system processes.references/dynamic-loading-and-interposition.md-dlopen/dlsymprotocol, a complete C interposing lab, saved-IMP method replacement, URLSession observation, Simulator launch environments.references/signing-and-attach-diagnostics.md- which layer failed,codesignand profile inspection, entitlements, re-signing rules, own-appptraceandsysctlchecks.references/custom-commands.md-.lldbinitlocations and precedence,command alias,command regex, Python commands, breakpoint callbacks, type summaries and synthetic children, third-party command packages, a starter.lldbinit.references/advanced-python.md- the bundledadb-lookup,adb-methods,adb-block,SBValuediscipline, expression ownership, allocation stack logging, debugging the debugger script.references/tracing-and-dtrace.md- breakpoint tracers, stop hooks, unified logging, hang sampling, DTrace providers and scripts, static probes.references/advanced-dtrace.md- thread-local and recursion-aware correlation, syscall arguments,copyin/copyinstr,stop,raise,copyout,system.references/remote-and-tooling.md-debugserverand platform connections,lldb-dap, LLDB MCP, custom breakpoint resolvers, scripted processes, threads, and thread plans.references/playbooks.md- step-by-step recipes for the common cases.references/anti-patterns.md- mistakes that cost the most time, with fixes.scripts/apple_debug_tools.py- session-localadb-lookup,adb-methods,adb-blockcommands.scripts/uitools.py-vmoveandfviewfor UIKit layout work while paused.
WWDC sessions behind this material: WWDC18 412 "Advanced Debugging with Xcode and LLDB", WWDC18 416 "iOS Memory Deep Dive", WWDC19 429 "LLDB: Beyond po", WWDC21 10209 "Discover breakpoint improvements", WWDC21 10211 "Symbolication: Beyond the basics", WWDC22 110370 "Debug Swift debugging with LLDB", WWDC24 10198 "Run, Break, Inspect: Explore effective debugging in LLDB".
Commands were checked against Apple LLDB lldb-2103.0.34.407 with Swift 6.4.2 on arm64 macOS. When a spelling differs on another Xcode, the installed debugger's help wins.