🇺🇸English

SwiftUI Debugging Diagnostics

When to Use This Diagnostic Skill

Use this skill when:

• Basic troubleshooting failed — Applied axiom-swiftui-debugging skill patterns but issue persists
• Self._printChanges() shows unexpected patterns — View updating when it shouldn't, or not updating when it should
• Intermittent issues — Works sometimes, fails other times ("heisenbug")
• Complex dependency chains — Need to trace data flow through multiple views/models
• Performance investigation — Views updating too often or taking too long
• Preview mysteries — Crashes or failures that aren't immediately obvious

FORBIDDEN Actions

Under pressure, you'll be tempted to shortcuts that hide problems instead of diagnosing them. NEVER do these :

❌ Guessing with random @State/@Observable changes

• "Let me try adding @Observable here and see if it works"
• "Maybe if I change this to @StateObject it'll fix it"

❌ Adding .id(UUID()) to force updates

• Creates new view identity every render
• Destroys state preservation
• Masks root cause

❌ Using ObservableObject when @Observable would work (iOS 17+)

• Adds unnecessary complexity
• Miss out on automatic dependency tracking

❌ Ignoring intermittent issues ("works sometimes")

• "I'll just merge and hope it doesn't happen in production"
• Intermittent = systematic bug, not randomness

❌ Shipping without understanding

• "The fix works, I don't know why"
• Production is too expensive for trial-and-error

Mandatory First Steps

Before diving into diagnostic patterns, establish baseline environment:

# 1. Verify Instruments setup
xcodebuild -version  # Must be Xcode 26+ for SwiftUI Instrument

# 2. Build in Release mode for profiling
xcodebuild build -scheme YourScheme -configuration Release

# 3. Clear derived data if investigating preview issues
rm -rf ~/Library/Developer/Xcode/DerivedData

Time cost : 5 minutes Why : Wrong Xcode version or Debug mode produces misleading profiling data

Diagnostic Decision Tree

SwiftUI view issue after basic troubleshooting?
│
├─ View not updating?
│  ├─ Basic check: Add Self._printChanges() temporarily
│  │  ├─ Shows "@self changed" → View value changed
│  │  │  └─ Pattern D1: Analyze what caused view recreation
│  │  ├─ Shows specific state property → That state triggered update
│  │  │  └─ Verify: Should that state trigger update?
│  │  └─ Nothing logged → Body not being called at all
│  │     └─ Pattern D3: View Identity Investigation
│  └─ Advanced: Use SwiftUI Instrument
│     └─ Pattern D2: SwiftUI Instrument Investigation
│
├─ View updating too often?
│  ├─ Pattern D1: Self._printChanges() Analysis
│  │  └─ Identify unnecessary state dependencies
│  └─ Pattern D2: SwiftUI Instrument → Cause & Effect Graph
│     └─ Trace data flow, find broad dependencies
│
├─ Intermittent issues (works sometimes)?
│  ├─ Pattern D3: View Identity Investigation
│  │  └─ Check: Does identity change unexpectedly?
│  ├─ Pattern D4: Environment Dependency Check
│  │  └─ Check: Environment values changing frequently?
│  └─ Reproduce in preview 30+ times
│     └─ If can't reproduce: Likely timing/race condition
│
└─ Preview crashes (after basic fixes)?
    ├─ Pattern D5: Preview Diagnostics (Xcode 26)
    │  └─ Check diagnostics button, crash logs
    └─ If still fails: Pattern D2 (profile preview build)

Diagnostic Patterns

Pattern D1: Self._printChanges() Analysis

Time cost : 5 minutes

Symptom : Need to understand exactly why view body runs

When to use :

• View updating more often than expected
• View not updating when it should
• Verifying dependencies after refactoring

Technique :

struct MyView: View {
    @State private var count = 0
    @Environment(AppModel.self) private var model

    var body: some View {
        let _ = Self._printChanges()  // Add temporarily

        VStack {
            Text("Count: \(count)")
            Text("Model value: \(model.value)")
        }
    }
}

Output interpretation :

# Scenario 1: View parameter changed
MyView: @self changed
→ Parent passed new MyView instance
→ Check parent code - what triggered recreation?

# Scenario 2: State property changed
MyView: count changed
→ Local @State triggered update
→ Expected if you modified count

# Scenario 3: Environment property changed
MyView: @self changed  # Environment is part of @self
→ Environment value changed (color scheme, locale, custom value)
→ Pattern D4: Check environment dependencies

# Scenario 4: Nothing logged
→ Body not being called
→ Pattern D3: View identity investigation

Common discoveries :

1. "@self changed" when you don't expect

   • Parent recreating view unnecessarily
   • Check parent's state management

2. Property shows changed but you didn't change it

   • Indirect dependency (reading from object that changed)
   • Pattern D2: Use Instruments to trace

3. Multiple properties changing together

   • Broad dependency (e.g., reading entire array when only need one item)
   • Fix: Extract specific dependency

Verification :

• Remove Self._printChanges() call before committing
• Never ship to production with this code

Cross-reference : For complex cases, use Pattern D2 (SwiftUI Instrument)

Pattern D2: SwiftUI Instrument Investigation

Time cost : 25 minutes

Symptom : Complex update patterns that Self._printChanges() can't fully explain

When to use :

• Multiple views updating when one should
• Need to trace data flow through app
• Views updating but don't know which data triggered it
• Long view body updates (performance issue)

Prerequisites :

• Xcode 26+ installed
• Device updated to iOS 26+ / macOS Tahoe+
• Build in Release mode

Steps :

1. Launch Instruments (5 min)

# Build Release
xcodebuild build -scheme YourScheme -configuration Release

# Launch Instruments
# Press Command-I in Xcode
# Choose "SwiftUI" template

2. Record Trace (3 min)

• Click Record button
• Perform the action that triggers unexpected updates
• Stop recording (10-30 seconds of interaction is enough)

3. Analyze Long View Body Updates (5 min)

• Look at Long View Body Updates lane
• Any orange/red bars? Those are expensive views
• Click on a long update → Detail pane shows view name
• Right-click → "Set Inspection Range and Zoom"
• Switch to Time Profiler track
• Find your view in call stack
• Identify expensive operation (formatter creation, calculation, etc.)

Fix : Move expensive operation to model layer, cache result

4. Analyze Unnecessary Updates (7 min)

• Highlight time range of user action (e.g., tapping favorite button)
• Expand hierarchy in detail pane
• Count updates — more than expected?
• Hover over view → Click arrow → "Show Cause & Effect Graph"

5. Interpret Cause & Effect Graph (5 min)

Graph nodes :

[Blue node] = Your code (gesture, state change, view body)
[System node] = SwiftUI/system work
[Arrow labeled "update"] = Caused this update
[Arrow labeled "creation"] = Caused view to appear

Common patterns :

# Pattern A: Single view updates (GOOD)
[Gesture] → [State Change in ViewModelA] → [ViewA body]

# Pattern B: All views update (BAD - broad dependency)
[Gesture] → [Array change] → [All list item views update]
└─ Fix: Use granular view models, one per item

# Pattern C: Cascade through environment (CHECK)
[State Change] → [Environment write] → [Many view bodies check]
└─ If environment value changes frequently → Pattern D4 fix

Click on nodes :

• State change node → See backtrace of where value was set
• View body node → See which properties it read (dependencies)

Verification :

• Record new trace after fix
• Compare before/after update counts
• Verify red/orange bars reduced or eliminated

Cross-reference : axiom-swiftui-performance skill for detailed Instruments workflows

Pattern D3: View Identity Investigation

Time cost : 15 minutes

Symptom : @State values reset unexpectedly, or views don't animate

When to use :

• Counter resets to 0 when it shouldn't
• Animations don't work (view pops instead of animates)
• ForEach items jump around
• Text field loses focus

Root cause : View identity changed unexpectedly

Investigation steps :

1. Check for conditional placement (5 min)

// ❌ PROBLEM: Identity changes with condition
if showDetails {
    CounterView()  // Gets new identity each time showDetails toggles
}

// ✅ FIX: Use .opacity()
CounterView()
    .opacity(showDetails ? 1 : 0)  // Same identity always

Find : Search codebase for views inside if/else that hold state

2. Check .id() modifiers (5 min)

// ❌ PROBLEM: .id() changes when data changes
DetailView()
    .id(item.id + "-\(isEditing)")  // ID changes with isEditing

// ✅ FIX: Stable ID
DetailView()
    .id(item.id)  // Stable ID

Find : Search codebase for .id( — check if ID values change

3. Check ForEach identifiers (5 min)

// ❌ WRONG: Index-based ID
ForEach(Array(items.enumerated()), id: \.offset) { index, item in
    Text(item.name)
}

// ❌ WRONG: Non-unique ID
ForEach(items, id: \.category) { item in  // Multiple items per category
    Text(item.name)
}

// ✅ RIGHT: Unique, stable ID
ForEach(items, id: \.id) { item in
    Text(item.name)
}

Find : Search for ForEach — verify unique, stable IDs

Fix patterns :

Verification :

• Add Self._printChanges() — should NOT see "@self changed" repeatedly
• Animations should now work smoothly
• @State values should persist

Pattern D4: Environment Dependency Check

Time cost : 10 minutes

Symptom : Many views updating when unrelated data changes

When to use :

• Cause & Effect Graph shows "Environment" node triggering many updates
• Slow scrolling or animation performance
• Unexpected cascading updates

Root cause : Frequently-changing value in environment OR too many views reading environment

Investigation steps :

1. Find environment writes (3 min)

# Search for environment modifiers in current project
grep -r "\.environment(" --include="*.swift" .

Look for :

// ❌ BAD: Frequently changing values
.environment(\.scrollOffset, scrollOffset)  // Updates 60+ times/second
.environment(model)  // If model updates frequently

// ✅ GOOD: Stable values
.environment(\.colorScheme, .dark)
.environment(appModel)  // If appModel changes rarely

2. Check what's in environment (3 min)

Using Pattern D2 (Instruments), check Cause & Effect Graph:

• Click on "Environment" node
• See which properties changed
• Count how many views checked for updates

Questions :

• Is this value changing every scroll/animation frame?
• Do all these views actually need this value?

3. Apply fix (4 min)

Fix A: Remove from environment (if frequently changing):

// ❌ Before: Environment
.environment(\.scrollOffset, scrollOffset)

// ✅ After: Direct parameter
ChildView(scrollOffset: scrollOffset)

Fix B: Use @Observable model (if needed by many views):

// Instead of storing primitive in environment:
@Observable class ScrollViewModel {
    var offset: CGFloat = 0
}

// Views depend on specific properties:
@Environment(ScrollViewModel.self) private var viewModel

var body: some View {
    Text("\(viewModel.offset)")  // Only updates when offset changes
}

Verification :

• Record new trace in Instruments
• Check Cause & Effect Graph — fewer views should update
• Performance should improve (smoother scrolling/animations)

Pattern D5: Preview Diagnostics (Xcode 26)

Time cost : 10 minutes

Symptom : Preview won't load or crashes with unclear error

When to use :

• Preview fails after basic fixes (swiftui-debugging skill)
• Error message unclear or generic
• Preview worked before, stopped suddenly

Investigation steps :

1. Use Preview Diagnostics Button (2 min)

Location : Editor menu → Canvas → Diagnostics

What it shows :

• Detailed error messages
• Missing dependencies
• State initialization issues
• Preview-specific problems

2. Check crash logs (3 min)

# Open crash logs directory
open ~/Library/Logs/DiagnosticReports/

# Look for recent .crash files containing "Preview"
ls -lt ~/Library/Logs/DiagnosticReports/ | grep -i preview | head -5

What to look for :

• Fatal errors (array out of bounds, force unwrap nil)
• Missing module imports
• Framework initialization failures

3. Isolate the problem (5 min)

Create minimal preview :

// Start with empty preview
#Preview {
    Text("Test")
}

// If this works, gradually add:
#Preview {
    MyView()  // Your actual view, but with mock data
        .environment(MockModel())  // Provide all dependencies
}

// Find which dependency causes crash

Common issues :

Fix patterns :

// Missing @Environment
#Preview {
    ContentView()
        .environment(AppModel())  // Provide dependency
}

// Missing @EnvironmentObject (pre-iOS 17)
#Preview {
    ContentView()
        .environmentObject(AppModel())
}

// Missing ModelContainer (SwiftData)
#Preview {
    let config = ModelConfiguration(isStoredInMemoryOnly: true)
    let container = try! ModelContainer(for: Item.self, configurations: config)

    return ContentView()
        .modelContainer(container)
}

// State with invalid defaults
@State var selectedIndex = 10  // ❌ Out of bounds
let items = ["a", "b", "c"]

// Fix: Safe default
@State var selectedIndex = 0  // ✅ Valid index

Verification :

• Preview loads without errors
• Can interact with preview normally
• Changes reflect immediately

Production Crisis Scenario

The Situation

Context :

• iOS 26 build shipped 2 days ago
• Users report "settings screen freezes when toggling features"
• 15% of users affected (reported via App Store reviews)
• VP asking for updates every 2 hours
• 8 hours until next deployment window closes
• Junior engineer suggests: "Let me try switching to @ObservedObject"

Red Flags — Resist These

If you hear ANY of these under deadline pressure, STOP and use diagnostic patterns :

❌ "Let me try different property wrappers and see what works"

• Random changes = guessing
• 80% chance of making it worse

❌ "It works on my device, must be iOS 26 bug"

• User reports are real
• 15% = systematic issue, not edge case

❌ "We can roll back if the fix doesn't work"

• App Store review takes 24 hours
• Rollback isn't instant

❌ "Add .id(UUID()) to force refresh"

• Destroys state preservation
• Hides root cause

❌ "Users will accept degraded performance for now"

• Once shipped, you're committed for 24 hours
• Bad reviews persist

Mandatory Protocol (No Shortcuts)

Total time budget : 90 minutes

Phase 1: Reproduce (15 min)

# 1. Get exact steps from user report
# 2. Build Release mode
xcodebuild build -scheme YourApp -configuration Release

# 3. Test on device (not simulator)
# 4. Reproduce freeze 3+ times

If can't reproduce : Ask for video recording or device logs from affected users

Phase 2: Diagnose with Pattern D2 (30 min)

# Launch Instruments with SwiftUI template
# Command-I in Xcode

# Record while reproducing freeze
# Look for:
# - Long View Body Updates (red bars)
# - Cause & Effect Graph showing update cascade

Find :

• Which view is expensive?
• What data change triggered it?
• How many views updated?

Phase 3: Apply Targeted Fix (20 min)

Based on diagnostic findings:

If Long View Body Update :

// Example finding: Formatter creation in body
// Fix: Move to cached formatter

If Cascade Update :

// Example finding: All toggle views reading entire settings array
// Fix: Per-toggle view models with granular dependencies

If Environment Issue :

// Example finding: Environment value updating every frame
// Fix: Remove from environment, use direct parameter

Phase 4: Verify (15 min)

# Record new Instruments trace
# Compare before/after:
# - Long updates eliminated?
# - Update count reduced?
# - Freeze gone?

# Test on device 10+ times

Phase 5: Deploy with Evidence (10 min)

Slack to VP + team:

"Diagnostic complete: Settings screen freeze caused by formatter creation
in ToggleRow body (confirmed via SwiftUI Instrument, Long View Body Updates).

Each toggle tap recreated NumberFormatter + DateFormatter for all visible
toggles (20+ formatters per tap).

Fix: Cached formatters in SettingsViewModel, pre-formatted strings.
Verified: Settings screen now responds in <16ms (was 200ms+).

Deploying build 2.1.1 now. Will monitor for next 24 hours."

This shows :

• You diagnosed with evidence (not guessed)
• You understand the root cause
• You verified the fix
• You're shipping with confidence

Time Cost Comparison

Option A: Guess and Pray

• Time to try random fixes: 30 min
• Time to deploy: 20 min
• Time to learn it failed: 24 hours (next App Store review)
• Total delay: 24+ hours
• User suffering: Continues through deployment window
• Risk: Made it worse, now TWO bugs

Option B: Diagnostic Protocol (This Skill)

• Time to diagnose: 45 min
• Time to apply targeted fix: 20 min
• Time to verify: 15 min
• Time to deploy: 10 min
• Total time: 90 minutes
• User suffering: Stopped after 2 hours
• Confidence: High (evidence-based fix)

Savings : 22 hours + avoid making it worse

When Pressure is Legitimate

Sometimes managers are right to push for speed. Accept the pressure IF:

✅ You've completed diagnostic protocol (90 minutes) ✅ You know exact view/operation causing issue ✅ You have targeted fix, not a guess ✅ You've verified in Instruments before shipping ✅ You're shipping WITH evidence, not hoping

Document your decision (same as above Slack template)

Professional Script for Pushback

If pressured to skip diagnostics:

"I understand the urgency. Skipping diagnostics means 80% chance of shipping the wrong fix, committing us to 24 more hours of user suffering. The diagnostic protocol takes 90 minutes total and gives us evidence-based confidence. We'll have the fix deployed in under 2 hours, verified, with no risk of making it worse. The math says diagnostics is the fastest path to resolution."

Quick Reference Table

Decision Framework

Before shipping ANY fix:

Answer YES to all five → Ship with confidence

Common Mistakes

Mistake 1: "I added @Observable and it fixed it"

Why it's wrong : You don't know WHY it fixed it

• Might work now, break later
• Might have hidden another bug

Right approach :

• Use Pattern D1 (Self._printChanges()) to see BEFORE state
• Apply @Observable
• Use Pattern D1 again to see AFTER state
• Understand exactly what changed

Mistake 2: "Instruments is too slow for quick fixes"

Why it's wrong : Guessing is slower when you're wrong

• 25 min diagnostic = certain fix
• 5 min guess × 3 failed attempts = 15 min + still broken

Right approach :

• Always profile for production issues
• Use Self._printChanges() for simple cases

Mistake 3: "The fix works, I don't need to verify"

Why it's wrong : Manual testing ≠ verification

• Might work for your specific test
• Might fail for edge cases
• Might have introduced performance regression

Right approach :

• Always verify in Instruments after fix
• Compare before/after traces
• Test edge cases (empty data, large data, etc.)

Quick Command Reference

Instruments Commands

# Launch Instruments with SwiftUI template
# 1. In Xcode: Command-I
# 2. Or from command line:
open -a Instruments

# Build in Release mode (required for accurate profiling)
xcodebuild build -scheme YourScheme -configuration Release

# Clean derived data if needed
rm -rf ~/Library/Developer/Xcode/DerivedData

Self._printChanges() Debug Pattern

// Add temporarily to view body
var body: some View {
    let _ = Self._printChanges()  // Shows update reason

    // Your view code
}

Remember : Remove before committing!

Preview Diagnostics

# Check preview crash logs
open ~/Library/Logs/DiagnosticReports/

# Filter for recent preview crashes
ls -lt ~/Library/Logs/DiagnosticReports/ | grep -i preview | head -5

# Xcode menu path:
# Editor → Canvas → Diagnostics

Environment Search

# Find environment modifiers
grep -r "\.environment(" --include="*.swift" .

# Find environment object usage
grep -r "@Environment" --include="*.swift" .

# Find view identity modifiers
grep -r "\.id(" --include="*.swift" .

Instruments Navigation

In Instruments (after recording) :

1. Select SwiftUI track
2. Expand to see:
   • Update Groups lane
   • Long View Body Updates lane
   • Long Representable Updates lane
3. Click Long View Body Updates summary
4. Right-click update → "Set Inspection Range and Zoom"
5. Switch to Time Profiler track
6. Find your view in call stack (Command-F)

Cause & Effect Graph:

1. Expand hierarchy in detail pane
2. Hover over view name → Click arrow
3. Choose "Show Cause & Effect Graph"
4. Click nodes to see:
   • State change node → Backtrace
   • View body node → Dependencies

Resources

WWDC : 2025-306, 2023-10160, 2023-10149, 2021-10022

Docs : /xcode/understanding-hitches-in-your-app, /xcode/analyzing-hangs-in-your-app, /swiftui/managing-model-data-in-your-app

Skills : axiom-swiftui-debugging, axiom-swiftui-performance, axiom-swiftui-layout, axiom-xcode-debugging

Weekly Installs

104

Repository

charleswiltgen/axiom

GitHub Stars

606

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode89

codex84

claude-code83

gemini-cli81

cursor80

github-copilot77