dev-skills

Appearance

Troubleshooting ​

Common pitfalls and fixes for Xcode builds, simulator issues, signing errors, and SwiftUI type-checker problems when developing with Claude Code.

When to use ​

Use when a build fails, the simulator misbehaves, XcodeBuildMCP isn't connecting, or SwiftUI is producing cryptic errors.

The pattern ​

XcodeBuildMCP won't start ​

  • Verify Node.js is installed: node --version (need v18+)
  • Verify npx works: npx --version
  • Check Xcode command line tools: xcode-select --install
  • Reinstall: claude mcp remove XcodeBuildMCP then re-add

Build fails with signing errors ​

  • Open the project in Xcode → Signing & Capabilities
  • Enable automatic signing and select your team (your Apple ID for personal development)
  • Don't use manual signing unless you have a specific reason
  • For multiplatform projects, check signing settings for each target separately

Simulator won't boot ​

  • List available simulators: xcrun simctl list devices
  • Verify the simulator name in .xcodebuildmcp/config.yaml matches an installed simulator exactly
  • If no simulators are available: Xcode → Settings → Platforms → download the simulator runtime for your target platform

UI automation returns empty hierarchy ​

  • The accessibility tree may be empty on the home screen, system dialogs, or apps without accessibility labels
  • Make sure your app is in the foreground with content on screen
  • Add accessibility labels to SwiftUI views: .accessibilityLabel("Save")

"Expression too complex" compiler errors ​

SwiftUI's type checker can choke on deeply nested view expressions. Fix by:

  • Extracting sub-views: move sections of the body into separate View structs
  • Adding explicit type annotations
  • Breaking complex ternaries or conditionals into computed properties

.pbxproj corruption ​

If Claude Code accidentally edits .pbxproj and Xcode rejects the project:

  • git checkout -- MyApp.xcodeproj/project.pbxproj to restore
  • Re-add any new files through Xcode's GUI or XcodeBuildMCP's project tools
  • Prevention: don't let Claude Code edit .xcodeproj files directly

Build succeeds but app crashes on launch ​

  • Use XcodeBuildMCP's debugging tools: debugging/attach then debugging/backtrace to see the crash site
  • Common cause: missing @Model macro on SwiftData classes, or forgetting to inject the model container via .modelContainer()
  • Check the simulator logs for the crash reason

Platform-specific issues ​

  • watchOS: Smaller API surface — some SwiftUI views aren't available. Check #available annotations.
  • macOS: Window management, menu bar, and keyboard shortcuts behave differently from iOS. Use .commands modifier for menu items.
  • iPad: Test with and without keyboard/trackpad connected — layout can change significantly.

Slow builds ​

  • SwiftUI type checking is the usual culprit — see "Expression too complex" above
  • Clean the build folder: Product → Clean Build Folder in Xcode
  • Derived Data can grow large — delete periodically from ~/Library/Developer/Xcode/DerivedData/

Trade-offs ​

  • Most troubleshooting requires Xcode's GUI for at least the initial diagnosis — Claude Code can fix code but can't click through Xcode's settings panels
  • Signing and provisioning issues are the most common blockers for new developers — automatic signing solves 90% of cases