Debugging with Xcode and LLDB

The WWDC24 session Run, Break, Inspect frames debugging as a search problem: each stop should cut the space where the bug can hide. Good breakpoints stop late enough that the state is interesting and early enough that it is not yet corrupted; good inspection answers one question per stop.

See Apple Developer Documentation — Stepping through code and inspecting variables to isolate bugs and WWDC24 — Run, Break, Inspect: Explore effective debugging in LLDB.

Click the gutter next to a line to add a breakpoint; drag it away to remove it. The Breakpoint navigator (Command-8) lists every breakpoint in the workspace, lets you name them, filter them and switch them on or off, and the breakpoint button in the debug bar activates or deactivates all of them at once. The same breakpoint can be created from the LLDB console, which is handy when you want to add one while the app is paused without reaching for the mouse:

See Apple Developer Documentation — Setting breakpoints to pause your running app.

Here line 71 stands for the first line of NoteStore's togglePin(_:) (from Persisting Models with SwiftData); use the line number your file has. A breakpoint on a line inside a Swift package works the same way as one in the app target, as long as the package is built from source.

The "pin toggles back" bug only happens for some notes. Stopping on every togglePin(_:) call would be slow, so the breakpoint gets a condition. Control-click the breakpoint, choose Edit Breakpoint, and enter an expression that uses variables in scope; the debugger evaluates it at every hit and stops only when it is true. The Ignore field skips the first n hits, for bugs that appear after a number of iterations.

A breakpoint can also run actions instead of stopping: Log Message, Debugger Command, Shell Command, AppleScript or Sound. With Automatically continue after evaluating actions selected, the breakpoint becomes a temporary log statement that needs no rebuild. In a Log Message action, text between @ characters is evaluated as an expression, so togglePin: @note.title@ pinned=@note.isPinned@ prints the note each time. The LLDB equivalent of that edited breakpoint is:

See Apple Developer Documentation — Setting breakpoints to pause your running app.

Log-and-continue breakpoints are cheaper than print statements you must remember to delete, but they are much slower than real code: each hit stops the process, runs the action, and resumes it. For a line that runs thousands of times per second, add a permanent Logger call instead (see Logging, MetricKit, Crash Reports and Organizer).

A symbolic breakpoint stops on a function by name, including functions you have no source for. Add one from the + button at the bottom of the Breakpoint navigator. The classic UIKit example is UIViewAlertForUnsatisfiableConstraints, which stops when Auto Layout breaks a constraint in one of the UIKit screens FieldNotes still hosts. For Swift code, a regular expression is often easier than an exact mangled name:

See Apple Developer Documentation — Setting breakpoints to pause your running app.

A symbol that fires very often (a layout method, objc_msgSend) makes the app unusable. Leave such a breakpoint disabled, stop at a breakpoint in your own code first, then enable it.

When a try! crashes, the debugger shows the try! line, not the place where the error was thrown. A Swift Error Breakpoint stops at the throw itself. An Exception Breakpoint does the same for Objective-C (and C++) exceptions, which otherwise surface in main or the app delegate with an unhelpful stack.

FieldNotes rarely uses try!, but NoteStore's write queue catches and logs persistence errors, so a failing save shows up only as a log line. A Swift error breakpoint catches the error at its source inside SwiftDataNotePersistence:

See Apple Developer Documentation — Setting breakpoints to pause your running app.

Errors thrown and caught on purpose (a cancelled Task.sleep, a CancellationError) also stop at a Swift error breakpoint. Give it a condition, or add it only while you chase one bug.

The sanitizers and the Main Thread Checker (covered below) report problems as purple runtime issues. By default they log and continue. A Runtime Issue Breakpoint pauses the app at the exact point the checker complains, with the offending thread selected. Add one from the + menu in the Breakpoint navigator and pick the issue type.

See Apple Developer Documentation — Setting breakpoints to pause your running app.

po runs debugDescription inside the app, which is slow and can have side effects, and the variables view doesn’t call it at all. The @DebugDescription macro converts a simple description into an LLDB type summary at compile time, so v, p and the variables view show it without running any code. FieldNotes adds one to Note:

See Apple Developer Documentation -- DebugDescription().

The description must be a single string interpolation of stored properties: no function calls, no conditionals and no computed properties (so tags.count is not allowed). With it, v note prints (FieldNotesModel.Note) note = "Beetle traps, site A [pinned: false]", and every Note in an array shows the same summary in the variables view.

When a view is missing, clipped or in the wrong place, click Debug View Hierarchy in the debug bar. Xcode pauses the app and shows the window as a 3D stack of layers, with the hierarchy in the Debug navigator and the selected view’s frame, constraints and properties in the inspectors. It works for SwiftUI and UIKit (and AppKit) views on iOS, iPadOS, macOS and watchOS. SwiftUI views appear as the platform views and layers they render to, so look for the hosting view and the SwiftUI-named nodes under it.

For layout questions it helps to make the frames visible in the running app too. FieldNotes keeps a debug-only modifier for that:

See Apple Developer Documentation — Diagnosing issues in the appearance of a running app.

On visionOS the view debugger is complemented by Debug Visualizations in the debug bar: axes, bounds, anchors and collision shapes for RealityKit content, and the occlusion mesh and surfaces the device detects. Use them for the notes map from Augmented Reality with ARKit and RealityKit; an entity that ignores taps usually lacks a collision shape.

Some bugs appear only with the largest Dynamic Type size, in Dark Mode, or with Increase Contrast. Environment Overrides in the debug bar change the interface style, the text size and a set of accessibility settings of the running app (on iOS, iPadOS and macOS) without touching the device’s Settings. Once an override reveals the bug, freeze the case in a preview so it stays fixed:

See Apple Developer Documentation — Diagnosing issues in the appearance of a running app.

Accessibility settings themselves, and the audits that go with them, are on Accessibility.

"Slower after opening the composer ten times" smells like a leak. While the app runs, the memory gauge in the Debug navigator shows current and peak use. Click Debug Memory Graph in the debug bar to pause the app and capture every heap object and the references between them. The navigator lists objects by type with instance counts, and a purple issue marks objects that are part of a leaked cycle: a set of objects that only reference each other and that nothing else can reach.

A graph shows what is alive; malloc stack logging adds where it was allocated. Turn on Malloc Stack Logging (live allocations only is enough) in the scheme’s Run > Diagnostics tab, and the inspector for each node shows the backtrace of its allocation. The same switches work from the command line, and an exported graph (File > Export Memory Graph) can be read with the leaks, heap and vmmap tools:

See Apple Developer Documentation — Gathering information about memory use.

Some secondary summaries of Xcode 27 say that the memory graph now also shows SwiftUI state graphs. Neither the Xcode 27 release notes nor Apple’s memory-use article mention this at the time of writing, so this page does not rely on it; the SwiftUI instrument on Performance and Instruments is the documented way to see why views update.

Hand-rolled DTrace scripts are largely superseded for this kind of work too: System Integrity Protection restricts DTrace unless it is deliberately disabled, so Instruments, together with os_signpost intervals, is the supported way to trace what DTrace used to cover (see Performance and Instruments). See Apple Developer Documentation — Disabling and enabling System Integrity Protection.

The figure shows the leak found with the memory graph below. Each solid arrow is a strong reference. Swift frees an object when no strong references remain, so a loop of strong references is never freed, even after the view that created it is gone.

See Apple Developer Documentation — Gathering information about memory use.

The first version of the composer’s autosave helper looked harmless. It stored the save logic in a closure and started its own loop:

See Apple Developer Documentation — Observation.

NoteDraft is the draft model from App Architecture the Apple Way. After opening and closing the composer ten times, the memory graph lists ten DraftAutosaver instances, each flagged as a leak; selecting one shows the path DraftAutosaver → closure context → DraftAutosaver, and with malloc stack logging on, the closure’s allocation backtrace points at init(draft:). The ten autosave loops are still running, too, which is why the app got slower.

The fix removes both strong loops. A stored closure that must refer back to its owner captures it weak, and a loop that should live as long as a view runs in that view’s .task, which SwiftUI cancels when the view disappears:

See Apple Developer Documentation -- task(name:priority:file:line:_:).

While run() is suspended, its task still holds the autosaver, but only until SwiftUI cancels the task when the composer closes; Task.sleep then throws and the loop returns. Capture lists and ownership rules are explained language-side on Automatic Reference Counting. To confirm the fix, repeat the ten open-and-close cycles and check that the memory graph shows no DraftAutosaver at all; the Allocations instrument’s generations on Performance and Instruments measure the same thing over a longer session.