# How to Troubleshoot XcodeBuildMCP Build Failures on iOS Simulators

> Troubleshoot XcodeBuildMCP build failures on iOS simulators. Inspect logs, retry with preferXcodebuild true, validate toolchain, and check scheme/bundle ID for quick solutions.

- Repository: [Thomas Ricouard/Skills](https://github.com/Dimillian/Skills)
- Tags: how-to-guide
- Published: 2026-04-01

---

**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`](https://github.com/Dimillian/Skills/blob/main/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`](https://github.com/Dimillian/Skills/blob/main/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`](https://github.com/Dimillian/Skills/blob/main/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:

```yaml

# 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`](https://github.com/Dimillian/Skills/blob/main/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.