Xcode Debugging

Overview

Check build environment BEFORE debugging code. Core principle 80% of "mysterious" Xcode issues are environment problems (stale Derived Data, stuck simulators, zombie processes), not code bugs.

Example Prompts

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

1. "My build is failing with 'BUILD FAILED' but no error details. I haven't changed anything. What's going on?"

→ The skill shows environment-first diagnostics: check Derived Data, simulator states, and zombie processes before investigating code

2. "Tests passed yesterday with no code changes, but now they're failing. This is frustrating. How do I fix this?"

→ The skill explains stale Derived Data and intermittent failures, shows the 2-5 minute fix (clean Derived Data)

3. "My app builds fine but it's running the old code from before my changes. I restarted Xcode but it still happens."

→ The skill demonstrates that Derived Data caches old builds, shows how deletion forces a clean rebuild

4. "The simulator says 'Unable to boot simulator' and I can't run tests. How do I recover?"

→ The skill covers simulator state diagnosis with simctl and safe recovery patterns (erase/shutdown/reboot)

5. "I'm getting 'No such module: SomePackage' errors after updating SPM dependencies. How do I fix this?"

→ The skill explains SPM caching issues and the clean Derived Data workflow that resolves "phantom" module errors

Red Flags — Check Environment First

If you see ANY of these, suspect environment not code:

• "It works on my machine but not CI"
• "Tests passed yesterday, failing today with no code changes"
• "Build succeeds but old code executes"
• "Build sometimes succeeds, sometimes fails" (intermittent failures)
• "Simulator stuck at splash screen" or "Unable to install app"
• Multiple xcodebuild processes (10+) older than 30 minutes

Mandatory First Steps

ALWAYS run these commands FIRST (before reading code):

# 1. Check processes (zombie xcodebuild?)
ps aux | grep -E "xcodebuild|Simulator" | grep -v grep

# 2. Check Derived Data size (>10GB = stale)
du -sh ~/Library/Developer/Xcode/DerivedData

# 3. Check simulator states (stuck Booting?)
xcrun simctl list devices | grep -E "Booted|Booting|Shutting Down"

What these tell you

• 0 processes + small Derived Data + no booted sims → Environment clean, investigate code
• 10+ processes OR >10GB Derived Data OR simulators stuck → Environment problem, clean first
• Stale code executing OR intermittent failures → Clean Derived Data regardless of size

Why environment first

• Environment cleanup: 2-5 minutes → problem solved
• Code debugging for environment issues: 30-120 minutes → wasted time

Quick Fix Workflow

Finding Your Scheme Name

If you don't know your scheme name:

# List available schemes
xcodebuild -list

For Stale Builds / "No such module" Errors

# Clean everything
xcodebuild clean -scheme YourScheme
rm -rf ~/Library/Developer/Xcode/DerivedData/*
rm -rf .build/ build/

# Rebuild
xcodebuild build -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16'

For Simulator Issues

# Shutdown all simulators
xcrun simctl shutdown all

# If simctl command fails, shutdown and retry
xcrun simctl shutdown all
xcrun simctl list devices

# If still stuck, erase specific simulator
xcrun simctl erase <device-uuid>

# Nuclear option: force-quit Simulator.app
killall -9 Simulator

For Zombie Processes

# Kill all xcodebuild (use cautiously)
killall -9 xcodebuild

# Check they're gone
ps aux | grep xcodebuild | grep -v grep

For Test Failures

# Isolate failing test
xcodebuild test -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16' \
  -only-testing:YourTests/SpecificTestClass

Simulator Verification (Optional)

After applying fixes, verify in simulator with visual confirmation.

Quick Screenshot Verification

# 1. Boot simulator (if not already)
xcrun simctl boot "iPhone 16 Pro"

# 2. Build and install app
xcodebuild build -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

# 3. Launch app
xcrun simctl launch booted com.your.bundleid

# 4. Wait for UI to stabilize
sleep 2

# 5. Capture screenshot
xcrun simctl io booted screenshot /tmp/verify-build-$(date +%s).png

Using Axiom Tools

Quick screenshot:

/axiom:screenshot

Full simulator testing (with navigation, state setup):

/axiom:test-simulator

When to Use Simulator Verification

Use when:

• Visual fixes — Layout changes, UI updates, styling tweaks
• State-dependent bugs — "Only happens in this specific screen"
• Intermittent failures — Need to reproduce specific conditions
• Before shipping — Final verification that fix actually works

Pro tip: If you have debug deep links (see axiom-deep-link-debugging skill), you can navigate directly to the screen that was broken:

xcrun simctl openurl booted "debug://problem-screen"
sleep 1
xcrun simctl io booted screenshot /tmp/fix-verification.png

Decision Tree

Test/build failing?
├─ BUILD FAILED with no details?
│  └─ Clean Derived Data → rebuild
├─ Build intermittent (sometimes succeeds/fails)?
│  └─ Clean Derived Data → rebuild
├─ Build succeeds but old code executes?
│  └─ Delete Derived Data → rebuild (2-5 min fix)
├─ "Unable to boot simulator"?
│  └─ xcrun simctl shutdown all → erase simulator
├─ "No such module PackageName"?
│  └─ Clean + delete Derived Data → rebuild
├─ Tests hang indefinitely?
│  └─ Check simctl list → reboot simulator
├─ Tests crash?
│  └─ Check ~/Library/Logs/DiagnosticReports/*.crash
└─ Code logic bug?
   └─ Use systematic-debugging skill instead

Common Error Patterns

Useful Flags

# Show build settings
xcodebuild -showBuildSettings -scheme YourScheme

# List schemes/targets
xcodebuild -list

# Verbose output
xcodebuild -verbose build -scheme YourScheme

# Build without testing (faster)
xcodebuild build-for-testing -scheme YourScheme
xcodebuild test-without-building -scheme YourScheme

Crash Log Analysis

# Recent crashes
ls -lt ~/Library/Logs/DiagnosticReports/*.crash | head -5

# Symbolicate address (if you have .dSYM)
atos -o YourApp.app.dSYM/Contents/Resources/DWARF/YourApp \
  -arch arm64 0x<address>

Common Mistakes

❌ Debugging code before checking environment — Always run mandatory steps first

❌ Ignoring simulator states — "Booting" can hang 10+ minutes, shutdown/reboot immediately

❌ Assuming git changes caused the problem — Derived Data caches old builds despite code changes

❌ Running full test suite when one test fails — Use -only-testing to isolate

Real-World Impact

Before 30+ min debugging "why is old code running" After 2 min environment check → clean Derived Data → problem solved

Key insight Check environment first, debug code second.