How to Troubleshoot XcodeBuildMCP Build Failures on iOS Simulators

To troubleshoot XcodeBuildMCP build failures on iOS simulators, inspect the raw compiler logs for specific error codes, retry the build with preferXcodebuild: true to bypass MCP-specific bugs, validate your Xcode 15+ toolchain alignment, and verify your scheme and bundle identifier using the MCP helper functions.

The Dimillian/Skills repository provides an iOS Debugger Agent that orchestrates the XcodeBuildMCP toolset to compile, launch, and interact with iOS apps on booted simulators. When builds fail, the agent follows a deterministic troubleshooting workflow defined in ios-debugger-agent/SKILL.md that emphasizes stateless re-querying and specific fallback strategies. Understanding these MCP function calls and error patterns allows developers to rapidly diagnose issues ranging from signing mismatches to architecture conflicts.

Understanding the XcodeBuildMCP Workflow

The agent executes three distinct phases when interacting with XcodeBuildMCP. Each phase uses specific MCP function names that map to underlying xcodebuild operations.

Simulator Discovery

First, the agent identifies a viable target device by calling mcp__XcodeBuildMCP__list_sims. This returns a JSON array of available simulators where you must select a device reporting state: "Booted" rather than Shutdown.

Session Configuration

Next, configure the build environment using mcp__XcodeBuildMCP__session-set-defaults. This function accepts parameters including projectPath, scheme, simulatorId, configuration, and useLatestOS. According to the source code in ios-debugger-agent/SKILL.md, these settings are re-queried each invocation to ensure the stateless agent respects any Xcode installation or project configuration changes.

Build and Run Execution

Finally, invoke mcp__XcodeBuildMCP__build_run_sim to compile and launch the binary. If this returns a failure status, the agent enters its troubleshooting mode, automatically suggesting retries with alternative parameters.

Common XcodeBuildMCP Failure Patterns and Solutions

Based on the troubleshooting section in ios-debugger-agent/SKILL.md, builds typically fail due to toolchain mismatches, signing issues, or destination errors. Here are the specific remediation steps for each symptom:

error: could not find module 'UIKit' This indicates missing or mismatched Xcode Command Line Tools. Run xcode-select --install and verify that XCODE_APP points to a valid Xcode bundle containing the iOS SDK.

Signing for "MyApp" requires a development team The project lacks code signing configuration. Either add a development team in the project's Signing & Capabilities settings, or pass -allowProvisioningUpdates via the XcodeBuildMCP flags to enable automatic provisioning.

Undefined symbols for architecture x86_64 You are likely building for the wrong architecture. Verify the ARCHS build setting. For iOS simulators, use x86_64 (Intel) or arm64 (Apple Silicon), ensuring you are not attempting to run macOS-only code on the simulator.

xcodebuild: error: Unable to find a destination matching... No booted simulator matches the requested device type or OS version. Re-run mcp__XcodeBuildMCP__list_sims to identify valid simulator IDs, boot the appropriate device, and update the simulatorId in your session defaults.

Build succeeds but app does not launch This occurs when the scheme points to a library target rather than an executable, or when the bundle identifier is stale. Use mcp__XcodeBuildMCP__get_app_bundle_id and mcp__XcodeBuildMCP__get_sim_app_path to confirm the binary location before attempting launch verification.

MCP crashes with Segmentation fault or SIGABRT The MCP binary is incompatible with your Xcode version. Certain MCP features require Xcode 15+. Update Xcode or downgrade the MCP binary to a compatible version.

Step-by-Step Troubleshooting Protocol

When mcp__XcodeBuildMCP__build_run_sim returns a failure, follow this exact sequence derived from the agent's core workflow:

1. Inspect the error output – The raw compiler log contains the exact failure reason, whether it is missing headers, Swift version mismatches, or signing issues.

2. Retry with legacy xcodebuild – Force the legacy path by adding preferXcodebuild: true to your build_run_sim arguments. This bypasses MCP-specific bugs while maintaining the same workflow.

3. Validate Xcode version – Check that you are running Xcode 15 or later. Mismatched toolchains surface as "unknown SDK" or "unsupported swift-frontend" errors.

4. Verify scheme and bundle identifier – Incorrect scheme names cause linker failures. Use mcp__XcodeBuildMCP__get_app_bundle_id to recover the correct identifier if unsure.

Verifying Successful Launch

After a successful build, confirm the app actually started before attempting UI interaction. The agent validates launch by calling:

• mcp__XcodeBuildMCP__describe_ui – Returns the UI hierarchy if the app is responsive
• mcp__XcodeBuildMCP__screenshot – Captures the current simulator screen

If these calls return data, the binary is confirmed running. If they fail, the build likely targeted a library instead of an executable app, requiring you to adjust the scheme in session-set-defaults.

YAML Configuration Examples

The following workflow illustrates the complete debugging sequence using the MCP function calls as implemented in the Skills repository:

# 1️⃣ Discover a booted simulator

- call: mcp__XcodeBuildMCP__list_sims
  result: |
    [
      {"id":"F1E2D3C4-5678-90AB-CDEF-1234567890AB","state":"Booted","name":"iPhone 15"},
      {"id":"...","state":"Shutdown","name":"iPad Pro (12.9-inch)"}
    ]

# 2️⃣ Set session defaults (project path, scheme, chosen simulator)

- call: mcp__XcodeBuildMCP__session-set-defaults
  args:
    projectPath: "./MyApp.xcodeproj"
    scheme: "MyApp"
    simulatorId: "F1E2D3C4-5678-90AB-CDEF-1234567890AB"
    configuration: "Debug"
    useLatestOS: true

# 3️⃣ Attempt a build & run

- call: mcp__XcodeBuildMCP__build_run_sim
  result: |
    {
      "status":"failure",
      "output":"error: signing for \"MyApp\" requires a development team..."
    }

# 4️⃣ Troubleshoot – retry with xcodebuild forced

- call: mcp__XcodeBuildMCP__build_run_sim
  args:
    preferXcodebuild: true
  result: |
    {
      "status":"success",
      "output":"Build Succeeded"
    }

# 5️⃣ Verify app launch

- call: mcp__XcodeBuildMCP__describe_ui
- call: mcp__XcodeBuildMCP__screenshot

Summary

• The iOS Debugger Agent in Dimillian/Skills uses XcodeBuildMCP functions like mcp__XcodeBuildMCP__build_run_sim to manage simulator builds.
• When builds fail, inspect logs and retry with preferXcodebuild: true to bypass MCP-specific issues.
• Validate your Xcode 15+ toolchain and ensure session-set-defaults references a booted simulator ID from list_sims.
• Use get_app_bundle_id and get_sim_app_path to resolve scheme-related launch failures.
• Confirm successful launches with describe_ui or screenshot before interacting with the app.

Frequently Asked Questions

What is XcodeBuildMCP in the Dimillian/Skills repository?

XcodeBuildMCP is a low-level bridge to xcodebuild and simulator control that exposes functions for listing simulators, setting session defaults, building projects, launching apps, and capturing UI state. According to ios-debugger-agent/SKILL.md, it serves as the compilation and execution backend for the iOS Debugger Agent, handling all interaction with the iOS simulator infrastructure through standardized MCP function calls.

How do I force XcodeBuildMCP to use legacy xcodebuild instead of MCP internals?

Pass preferXcodebuild: true as an argument to mcp__XcodeBuildMCP__build_run_sim. This forces the tool to use the traditional xcodebuild command-line path rather than MCP-specific build logic, which can resolve segmentation faults or incompatible toolchain errors caused by MCP binaries built for different Xcode versions.

Why does my build succeed but the app fail to launch on the iOS simulator?

This typically indicates the scheme points to a library target rather than an executable app, or the bundle identifier in the build settings does not match what the simulator expects. Use mcp__XcodeBuildMCP__get_app_bundle_id to retrieve the correct identifier, and verify the scheme targets an app bundle rather than a static or dynamic library before invoking build_run_sim.

Which Xcode version is required for XcodeBuildMCP compatibility?

Xcode 15 or later is required for full MCP feature support. Running XcodeBuildMCP with Xcode 14 or earlier often results in "unknown SDK" errors, swift-frontend failures, or segmentation faults, as the MCP binary may rely on toolchain features introduced in Xcode 15. Always verify your xcode-select path points to a valid Xcode 15+ bundle when troubleshooting mysterious MCP crashes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}