WebDriverAgent fails to start on iOS 26.2 / Xcode 26.2 simulator

[Shwinn]

Description

All tools that depend on WebDriverAgent fail with timed out waiting for WebDriverAgent to be ready on an iOS 26.2 simulator (Xcode 26.2). WebDriverAgent never starts — it attempts to listen on a port but the connection is permanently refused.

Environment

• macOS: 26.3.1 (arm64, Apple Silicon)
• Xcode: 26.2 (Build 17C52)
• iOS Simulator Runtime: iOS 26.2 (23C54)
• Simulator Device: iPhone 17 Pro (CF7B2DE4-A852-4CC8-9A43-1234F52A7798)
• mobile-mcp: 0.0.50 (latest via `npx -y @mobilenext/mobile-mcp@latest`)
• mobilecli: 0.1.60

Steps to Reproduce

1. Boot an iOS 26.2 simulator:

   xcrun simctl boot "iPhone 17 Pro"

2. Launch any app on the simulator (confirmed the app is running and visible via `xcrun simctl io screenshot`)
3. Attempt any mobile-mcp tool that requires WebDriverAgent:

   mobile_take_screenshot(device: "CF7B2DE4-...")
   mobile_list_elements_on_screen(device: "CF7B2DE4-...")
   

Observed Behavior

All WebDriverAgent-dependent tools fail with:

error starting agent: timed out waiting for WebDriverAgent to be ready

Verbose logs from mobilecli

Running mobilecli screenshot --device <UDID> --format png --output /tmp/test.png -v shows:

[VERBOSE] Could not find WDA process: WebDriverAgent process not found for device CF7B2DE4-...
[VERBOSE] Failed to get existing WDA port: WebDriverAgent process not found for device CF7B2DE4-...
[VERBOSE] Starting WebDriverAgent with USE_PORT=13002 and MJPEG_SERVER_PORT=13202
[VERBOSE] WebDriverAgent not ready yet: failed to fetch endpoint status: Get "http://localhost:13002/status": dial tcp [::1]:13002: connect: connection refused
[VERBOSE] WebDriverAgent not ready yet: ...  (repeats for ~30 seconds until timeout)

WebDriverAgent is never successfully started — port 13002 stays refused for the entire timeout duration.

What DOES work

• xcrun simctl io <UDID> screenshot — native simctl screenshots work fine
• mobile_list_elements_on_screen — worked once on the iOS home screen (SpringBoard), but failed on subsequent calls and always fails when an app is in the foreground
• mobile_launch_app — successfully launches apps
• mobile_list_available_devices — correctly lists the booted simulator

Likely Root Cause

The upstream Appium WebDriverAgent had a build failure on Xcode 26 due to a -Wno-reserved-identifier compiler flag issue, fixed in appium/WebDriverAgent#1032 and shipped in XCUITest driver 9.5.0+ / WDA v11.4.1 (2026-03-15).

If mobilecli bundles a WDA build that predates this fix, it would fail to compile/run under Xcode 26, which matches the observed behavior (WDA process never starts, port never opens).

The Appium team confirmed iOS 26 works after the fix: appium/appium#21347 (closed as resolved).

Related Issues

• mobilecli#186 — same "timed out waiting for WebDriverAgent to be ready" error on simulator, filed 2026-03-25

Additional Context

Only iOS 26.2 runtime is available with Xcode 26.2 — there is no option to use an older iOS runtime as a workaround without installing a separate Xcode version.

[Shwinn]

Confirmed workaround

The root cause is that mobilecli hardcodes a download of WebDriverAgent v10.2.5, which fails to build under Xcode 26.2 due to the -Wno-reserved-identifier compiler flag issue fixed in appium/WebDriverAgent#1032.

mobilecli already supports a MOBILECLI_WDA_PATH env var override, so the fix is straightforward — just point it at a newer WDA build:

# Download WDA v11.4.1 (the version with the Xcode 26 fix)
mkdir -p ~/.mobilecli/wda
curl -L -o ~/.mobilecli/wda/WebDriverAgentRunner-Build-Sim-arm64.zip \
  https://github.com/appium/WebDriverAgent/releases/download/v11.4.1/WebDriverAgentRunner-Build-Sim-arm64.zip

# Tell mobilecli to use it (add to ~/.zshrc or equivalent)
export MOBILECLI_WDA_PATH="$HOME/.mobilecli/wda"

Restart your terminal / MCP host after setting the env var. All WDA-dependent tools (mobile_take_screenshot, mobile_list_elements_on_screen, etc.) work after this.

The permanent fix would be for mobilecli to bump the hardcoded WDA version from v10.2.5 → v11.4.1+ in devices/simulator.go line 304.

[gmegidish]

@Shwinn that's great! thank you. I'll review this and fix this in mobilecli, simulator.go :) THANK YOU!