Context

When running iOS simulator builds, you may encounter a situation where xcrun simctl bootstatus <udid> -b never returns, freezing at the following output:

[...] Status=1, isTerminal=NO, Elapsed=00:04.
    Waiting on BackBoard

The simulator itself may appear healthy — simctl list reports it as (Booted), and both backboardd and SpringBoard are running — but the readiness handshake back to CoreSimulator is never completed, causing the build to hang indefinitely.

Answer

This hang is typically caused by a runtime mismatch: the workflow is using one version of Xcode but the simulator device selected is running an older iOS runtime. For example, if your workflow uses Xcode 26.1.1 but your device lookup picks up an iOS 26.0 device (because it returns the first matching device), the mismatch can cause the BackBoard readiness notification to be lost with no retry or re-check.

To resolve this, explicitly select the simulator runtime that matches your Xcode version rather than relying on the first device returned. You can do this with the following snippet:

SDKV=$(xcrun --sdk iphonesimulator --show-sdk-version)
RUNTIME="com.apple.CoreSimulator.SimRuntime.iOS-${SDKV//./-}"
udid=$(xcrun simctl create ci-sim "iPhone 17 Pro" "$RUNTIME")

This ensures the simulator runtime always matches the SDK bundled with the Xcode version in use. Note that Xcode images may include multiple runtimes (e.g., both iOS 26.0 and iOS 26.1), so without explicit selection, an older runtime may be picked up unintentionally.

Enabling SSH access via the API

If you need to debug intermittent simulator hangs live, you can enable SSH access when triggering a build through the Codemagic v3 API. Set ssh_access_enabled to true in your POST /api/v3/apps/{app_id}/builds request:

{
  "workflow_id": "<workflow_id>",
  "branch": "<branch>",
  "ssh_access_enabled": true
}

For full details, refer to the Codemagic API schema.