axiom-swiftui-nav-diag

SwiftUI Navigation Diagnostics

Overview

Core principle 85% of navigation problems stem from path state management errors, view identity issues, or placement mistakes—not SwiftUI defects.

SwiftUI's navigation system is used by millions of apps and handles complex navigation patterns reliably. If your navigation is failing, not responding, or behaving unexpectedly, the issue is almost always in how you're managing navigation state, not the framework itself.

This skill provides systematic diagnostics to identify root causes in minutes, not hours.

Red Flags — Suspect Navigation Issue

If you see ANY of these, suspect a code issue, not framework breakage:

• Navigation tap does nothing (link present but doesn't push)

• Back button pops to wrong screen or root

• Deep link opens app but shows wrong screen

• Navigation state lost when switching tabs

• Navigation state lost when app backgrounds

• Same NavigationLink pushes twice

• Navigation animation stuck or janky

• Crash with navigationDestination in stack trace

• ❌ FORBIDDEN "SwiftUI navigation is broken, let's wrap UINavigationController"

  • NavigationStack is used by Apple's own apps
  • Wrapping UIKit adds complexity and loses SwiftUI state management benefits
  • UIKit interop has its own edge cases you'll spend weeks discovering
  • Your issue is almost certainly path management, not framework defect

Critical distinction NavigationStack behavior is deterministic. If it's not working, you're modifying state incorrectly, have view identity issues, or navigationDestination is misplaced.

Mandatory First Steps

ALWAYS run these checks FIRST (before changing code):

// 1. Add NavigationPath logging
NavigationStack(path: $path) {
    RootView()
        .onChange(of: path.count) { oldCount, newCount in
            print("📍 Path changed: \(oldCount) → \(newCount)")
            // If this never fires, link isn't modifying path
            // If it fires unexpectedly, something else modifies path
        }
}

// 2. Check navigationDestination is visible
// Put temporary print in destination closure
.navigationDestination(for: Recipe.self) { recipe in
    let _ = print("🔗 Destination for Recipe: \(recipe.name)")
    RecipeDetail(recipe: recipe)
}
// If this never prints, destination isn't being evaluated

// 3. Check NavigationLink is inside NavigationStack
// Visual inspection: Trace from NavigationLink up view hierarchy
// Must hit NavigationStack, not another container first

// 4. Check path state location
// @State must be in stable view (not recreated each render)
// Must be @State, @StateObject, or @Observable — not local variable

// 5. Test basic case in isolation
// Create minimal reproduction
NavigationStack {
    NavigationLink("Test", value: "test")
        .navigationDestination(for: String.self) { str in
            Text("Pushed: \(str)")
        }
}
// If this works, problem is in your specific setup

What this tells you

Observation	Diagnosis	Next Step
onChange never fires on tap	NavigationLink not in NavigationStack hierarchy	Pattern 1a
onChange fires but view doesn't push	navigationDestination not found/loaded	Pattern 1b
onChange fires, view pushes, then immediate pop	View identity issue or path modification	Pattern 2a
Path changes unexpectedly (not from tap)	External code modifying path	Pattern 2b
Deep link path.append() doesn't navigate	Timing issue or wrong thread	Pattern 3b
State lost on tab switch	NavigationStack shared across tabs	Pattern 4a
Works first time, fails on return	View recreation issue	Pattern 5a

MANDATORY INTERPRETATION

Before changing ANY code, identify ONE of these:

1. If link tap does nothing AND no onChange → Link outside NavigationStack (check hierarchy)
2. If onChange fires but nothing pushes → navigationDestination not in scope (check placement)
3. If pushes then immediately pops → View identity change or path reset (check @State location)
4. If deep link fails → Timing or MainActor issue (check thread)
5. If crash → Force unwrap on path decode or missing type registration

If diagnostics are contradictory or unclear

• STOP. Do NOT proceed to patterns yet
• Add print statements at every path modification point
• Create minimal reproduction case
• Test with String values first (simplest case)

Decision Tree

Use this to reach the correct diagnostic pattern in 2 minutes:

Navigation problem?
├─ Navigation tap does nothing?
│  ├─ NavigationLink inside NavigationStack?
│  │  ├─ No → Pattern 1a (Link outside Stack)
│  │  └─ Yes → Check navigationDestination
│  │
│  ├─ navigationDestination registered?
│  │  ├─ Inside lazy container? → Pattern 1b (Lazy Loading)
│  │  ├─ Type mismatch? → Pattern 1c (Type Registration)
│  │  └─ Blocked by sheet/popover? → Pattern 1d (Modal Blocking)
│  │
│  └─ Using view-based link?
│     └─ → Pattern 1e (Deprecated API)
│
├─ Unexpected pop back?
│  ├─ Immediate pop after push?
│  │  ├─ View body recreating path? → Pattern 2a (Path Recreation)
│  │  ├─ @State in wrong view? → Pattern 2a (State Location)
│  │  └─ ForEach id changing? → Pattern 2c (Identity Change)
│  │
│  ├─ Pop when shouldn't?
│  │  ├─ External code calling removeLast? → Pattern 2b (Unexpected Modification)
│  │  ├─ Task cancelled? → Pattern 2b (Async Cancellation)
│  │  └─ MainActor issue? → Pattern 2d (Threading)
│  │
│  └─ Back button behavior wrong?
│     └─ → Pattern 2e (Stack Corruption)
│
├─ Deep link not working?
│  ├─ URL not received?
│  │  ├─ onOpenURL not called? → Check URL scheme in Info.plist
│  │  └─ Universal Links issue? → Check apple-app-site-association
│  │
│  ├─ URL received, path not updated?
│  │  ├─ path.append not on MainActor? → Pattern 3a (Threading)
│  │  ├─ Timing issue (app not ready)? → Pattern 3b (Initialization)
│  │  └─ NavigationStack not created yet? → Pattern 3b (Lifecycle)
│  │
│  └─ Path updated, wrong screen shown?
│     ├─ Wrong path order? → Pattern 3c (Path Construction)
│     ├─ Wrong type appended? → Pattern 3c (Type Mismatch)
│     └─ Item not found? → Pattern 3d (Data Resolution)
│
├─ State lost?
│  ├─ Lost on tab switch?
│  │  ├─ Shared NavigationStack? → Pattern 4a (Shared State)
│  │  └─ Tab recreation? → Pattern 4a (Tab Identity)
│  │
│  ├─ Lost on background/foreground?
│  │  ├─ No SceneStorage? → Pattern 4b (No Persistence)
│  │  └─ Decode failure? → Pattern 4c (Decode Error)
│  │
│  └─ Lost on rotation/size change?
│     └─ → Pattern 4d (Layout Recreation)
│
├─ NavigationSplitView issue?
│  ├─ Sidebar not visible on iPad?
│  │  ├─ columnVisibility not set? → Pattern 6a (Column Visibility)
│  │  └─ Compact size class? → Pattern 6a (Automatic Adaptation)
│  │
│  ├─ Detail shows blank on iPad?
│  │  ├─ No default detail view? → Pattern 6b (Missing Detail)
│  │  └─ Selection binding nil? → Pattern 6b (Selection State)
│  │
│  └─ Works on iPhone, broken on iPad?
│     └─ → Pattern 6c (Platform Adaptation)
│
└─ Crash?
   ├─ EXC_BAD_ACCESS in navigation code?
   │  └─ → Pattern 5a (Memory Issue)
   │
   ├─ Fatal error: type not registered?
   │  └─ → Pattern 5b (Missing Destination)
   │
   └─ Decode failure on restore?
      └─ → Pattern 5c (Restoration Crash)

Pattern Selection Rules (MANDATORY)

Before proceeding to a pattern:

1. Navigation tap does nothing → Add onChange logging FIRST, then Pattern 1
2. Unexpected pop → Find WHAT is modifying path (logging), then Pattern 2
3. Deep link fails → Verify URL received (print in onOpenURL), then Pattern 3
4. State lost → Identify WHEN lost (tab switch vs background), then Pattern 4
5. Crash → Get full stack trace, then Pattern 5

Apply ONE pattern at a time

• Implement the fix from one pattern
• Test thoroughly
• Only if issue persists, try next pattern
• DO NOT apply multiple patterns simultaneously (can't isolate cause)

FORBIDDEN

• Guessing at solutions without diagnostics
• Changing multiple things at once
• Wrapping with UINavigationController "because SwiftUI is broken"
• Adding delays/DispatchQueue.main.async without understanding why
• Switching to view-based NavigationLink "to avoid path issues"

---

Diagnostic Patterns

Pattern 1a: NavigationLink Outside NavigationStack

Time cost 5-10 minutes

Symptom

• Tapping NavigationLink does nothing
• No navigation occurs, no errors
• onChange(of: path) never fires

Diagnosis

// Check view hierarchy — NavigationLink must be INSIDE NavigationStack

// ❌ WRONG — Link outside stack
struct ContentView: View {
    var body: some View {
        VStack {
            NavigationLink("Go", value: "test")  // Outside stack!
            NavigationStack {
                Text("Root")
            }
        }
    }
}

// Check: Add background color to NavigationStack
NavigationStack {
    Color.red  // If link is on red, it's inside
}

Fix

// ✅ CORRECT — Link inside stack
struct ContentView: View {
    var body: some View {
        NavigationStack {
            VStack {
                NavigationLink("Go", value: "test")  // Inside stack
                Text("Root")
            }
            .navigationDestination(for: String.self) { str in
                Text("Pushed: \(str)")
            }
        }
    }
}

Verification

• Tap link, navigation occurs
• onChange(of: path) fires when tapped

---

Pattern 1b: navigationDestination in Lazy Container

Time cost 10-15 minutes

Symptom

• NavigationLink tap does nothing OR works intermittently
• onChange fires (path updated) but view doesn't push
• Console may show: "A navigationDestination for [Type] was not found"

Diagnosis

// ❌ WRONG — Destination inside lazy container (may not be loaded)
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            NavigationLink(item.name, value: item)
                .navigationDestination(for: Item.self) { 

---

*Content truncated.*