SwiftUI Debugging

Overview

SwiftUI debugging falls into three categories, each with a different diagnostic approach:

1. View Not Updating – You changed something but the view didn't redraw. Decision tree to identify whether it's struct mutation, lost binding identity, accidental view recreation, or missing observer pattern.
2. Preview Crashes – Your preview won't compile or crashes immediately. Decision tree to distinguish between missing dependencies, state initialization failures, and Xcode cache corruption.
3. Layout Issues – Views appearing in wrong positions, wrong sizes, overlapping unexpectedly. Quick reference patterns for common scenarios.

Core principle: Start with observable symptoms, test systematically, eliminate causes one by one. Don't guess.

Requires: Xcode 26+, iOS 17+ (iOS 14-16 patterns still valid, see notes) Related skills: axiom-xcode-debugging (cache corruption diagnosis), axiom-swift-concurrency (observer patterns), axiom-swiftui-performance (profiling with Instruments), axiom-swiftui-layout (adaptive layout patterns)

Example Prompts

These are real questions developers ask that this skill is designed to answer:

1. "My list item doesn't update when I tap the favorite button, even though the data changed"

→ The skill walks through the decision tree to identify struct mutation vs lost binding vs missing observer

2. "Preview crashes with 'Cannot find AppModel in scope' but it compiles fine"

→ The skill shows how to provide missing dependencies with .environment() or .environmentObject()

3. "My counter resets to 0 every time I toggle a boolean, why?"

→ The skill identifies accidental view recreation from conditionals and shows .opacity() fix

4. "I'm using @Observable but the view still doesn't update when I change the property"

→ The skill explains when to use @State vs plain properties with @Observable objects

5. "Text field loses focus when I start typing, very frustrating"

→ The skill identifies ForEach identity issues and shows how to use stable IDs

When to Use SwiftUI Debugging

Use this skill when

• ✅ A view isn't updating when you expect it to
• ✅ Preview crashes or won't load
• ✅ Layout looks wrong on specific devices
• ✅ You're tempted to bandaid with @ObservedObject everywhere

Use axiom-xcode-debugging instead when

• App crashes at runtime (not preview)
• Build fails completely
• You need environment diagnostics

Use axiom-swift-concurrency instead when

• Questions about async/await or MainActor
• Data race warnings

Debugging Tools

Self._printChanges()

SwiftUI provides a debug-only method to understand why a view's body was called.

Usage in LLDB:

// Set breakpoint in view's body
// In LLDB console:
(lldb) expression Self._printChanges()

Temporary in code (remove before shipping):

var body: some View {
    let _ = Self._printChanges() // Debug only

    Text("Hello")
}

Output interpretation:

MyView: @self changed
  - Means the view value itself changed (parameters passed to view)

MyView: count changed
  - Means @State property "count" triggered the update

MyView: (no output)
  - Body not being called; view not updating at all

⚠️ Important:

• Prefixed with underscore → May be removed in future releases
• NEVER submit to App Store with _printChanges calls
• Performance impact → Use only during debugging

When to use:

• Need to understand exact trigger for view update
• Investigating unexpected updates
• Verifying dependencies after refactoring

Cross-reference: For complex update patterns, use SwiftUI Instrument → see axiom-swiftui-performance skill

---

View Not Updating Decision Tree

The most common frustration: you changed @State but the view didn't redraw. The root cause is always one of four things.

Step 1: Can You Reproduce in a Minimal Preview?

#Preview {
  YourView()
}

YES → The problem is in your code. Continue to Step 2.

NO → It's likely Xcode state or cache corruption. Skip to Preview Crashes section.

Step 2: Diagnose the Root Cause

Root Cause 1: Struct Mutation

Symptom: You modify a @State value directly, but the view doesn't update.

Why it happens: SwiftUI doesn't see direct mutations on structs. You need to reassign the entire value.

// ❌ WRONG: Direct mutation doesn't trigger update
@State var items: [String] = []

func addItem(_ item: String) {
    items.append(item)  // SwiftUI doesn't see this change
}

// ✅ RIGHT: Reassignment triggers update
@State var items: [String] = []

func addItem(_ item: String) {
    var newItems = items
    newItems.append(item)
    self.items = newItems  // Full reassignment
}

// ✅ ALSO RIGHT: Use a binding
@State var items: [String] = []

var itemsBinding: Binding<[String]> {
    Binding(
        get: { items },
        set: { items = $0 }
    )
}

Fix it: Always reassign the entire struct value, not pieces of it.

---

Root Cause 2: Lost Binding Identity

Symptom: You pass a binding to a child view, but changes in the child don't update the parent.

Why it happens: You're passing .constant() or creating a new binding each time, breaking the two-way connection.

// ❌ WRONG: Constant binding is read-only
@State var isOn = false

ToggleChild(value: .constant(isOn))  // Changes ignored

// ❌ WRONG: New binding created each render
@State var name = ""

TextField("Name", text: Binding(
    get: { name },
    set: { name = $0 }
))  // New binding object each time parent renders

// ✅ RIGHT: Pass the actual binding
@State var isOn = false

ToggleChild(value: $isOn)

// ✅ RIGHT (iOS 17+): Use @Bindable for @Observable objects
@Observable class Book {
    var title = "Sample"
    var isAvailable = true
}

struct EditView: View {
    @Bindable var book: Book  // Enables $book.title syntax

    var body: some View {
        TextField("Title", text: $book.title)
        Toggle("Available", isOn: $book.isAvailable)
    }
}

// ✅ ALSO RIGHT (iOS 17+): @Bindable as local variable
struct ListView: View {
    @State private var books = [Book(), Book()]

    var body: some View {
        List(books) { book in
            @Bindable var book = book  // Inline binding
            TextField("Title", text: $book.title)
        }
    }
}

// ✅ RIGHT (pre-iOS 17): Create binding once, not in body
@State var name = ""
@State var nameBinding: Binding<String>?

var body: some View {
    if nameBinding == nil {
        nameBinding = Binding(
            get: { name },
            set: { name = $0 }
        )
    }
    return TextField("Name", text: nameBinding!)
}

Fix it: Pass $state directly when possible. For @Observable objects (iOS 17+), use @Bindable. If creating custom bindings (pre-iOS 17), create them in init or cache them, not in body.

---

Root Cause 3: Accidental View Recreation

Symptom: The view updates, but @State values reset to initial state. You see brief flashes of initial values.

Why it happens: The view got a new identity (removed from a conditional, moved in a container, or the container itself was recreated), causing SwiftUI to treat it as a new view.

// ❌ WRONG: View identity changes when condition flips
@State var count =