axiom-xcode-debugging
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
| Error | Fix |
|---|---|
BUILD FAILED (no details) |
Delete Derived Data |
Unable to boot simulator |
xcrun simctl erase <uuid> |
No such module |
Clean + delete Derived Data |
| Tests hang | Check simctl list, reboot simulator |
| Stale code executing | Delete Derived Data |
Useful CLI Tools
# 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
# Version and build number management (agvtool)
xcrun agvtool what-marketing-version # Current version (e.g., 2.0)
xcrun agvtool what-version # Current build number
xcrun agvtool next-version -all # Bump build number
xcrun agvtool new-version -all 42 # Set specific build number
xcrun agvtool new-marketing-version 2.1 # Set marketing version
# Validate asset catalogs
xcrun amlint Assets.xcassets # Lint for issues before build
Physical Device Management (devicectl)
devicectl is the modern CLI for physical device operations (replaces legacy idevice* tools).
# List connected devices
xcrun devicectl list devices
# Install app on device
xcrun devicectl device install app --device <udid> MyApp.app
# Launch app on device
xcrun devicectl device process launch --device <udid> com.your.bundleid
# List installed apps
xcrun devicectl device info apps --device <udid>
# List running processes
xcrun devicectl device info processes --device <udid>
When to use: Physical device debugging when the issue doesn't reproduce in Simulator — install, launch, and inspect from CLI.
Crash Log Analysis
# Recent crashes
ls -lt ~/Library/Logs/DiagnosticReports/*.crash | head -5
# Symbolicate a single address (if you have .dSYM)
xcrun atos -o YourApp.app.dSYM/Contents/Resources/DWARF/YourApp \
-arch arm64 -l 0x100000000 0x<address>
# Symbolicate an entire crash log at once (LLDB Python script, may vary by Xcode version)
xcrun crashlog MyCrash.ips
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.