Failure-mode library

Symptom-first writeups of the operational failures that show up around local XCTest, xcodebuild, simctl, and the iOS Simulator. Each page is useful on its own — quick checks and manual mitigations first, and an honest note on where XCSteward may or may not help.

Search by error message or stuck point

These are the kinds of phrases people paste after a local run wedges: simulator boot hangs, destination resolution stalls, simctl stops responding, or the test runner never attaches.

Destination & simulator readiness

Resolving a destination, booting a device, and getting it actually ready before tests start.

xcodebuild hangs resolving the simulator destination

xcodebuild stalls while resolving or selecting a simulator destination — sometimes for minutes — before a single test runs.

Strong fit Likely: destination resolution / CoreSimulator enumeration
xcodebuild destination unavailable or ineligible

xcodebuild errors out that the destination is unavailable or ineligible — no device matches the specifier — instead of running tests.

Partial fit Likely: destination matching / device eligibility
xcodebuild timed out waiting for the simulator

xcodebuild aborts with a timeout waiting for the simulator to boot or to be ready, instead of running the tests.

Strong fit Likely: boot/readiness timeout
Unable to boot the iOS simulator

Booting a simulator fails outright ("Unable to boot device") or the device sits in Booting forever and never reaches Booted.

Strong fit Likely: simulator boot failure
iOS simulator booted but tests never start

The simulator boots and reaches the home screen, but the app never launches and testing never begins — the run just sits there.

Strong fit Likely: post-boot readiness / app launch / test bundle install stall

CoreSimulator / simctl lifecycle

The simctl client and CoreSimulatorService daemon becoming unresponsive, wedged, or deadlocked.

simctl commands not responding or hanging

xcrun simctl commands (list, boot, shutdown, spawn) hang indefinitely and never return — even simple ones like simctl list.

Strong fit Likely: CoreSimulatorService unresponsive / simctl IPC stall
CoreSimulatorService deadlock and unresponsive simulators

CoreSimulatorService stops responding and the whole simulator subsystem wedges — simctl, Simulator.app, and xcodebuild all block at once.

Strong fit Likely: CoreSimulatorService deadlock / shared-state contention
Unable to connect to the iOS simulator

The device is up but the run cannot connect to it — the test runner never attaches, or you see "Unable to connect to" / lost-connection errors.

Partial fit Likely: test-runner / CoreSimulator connection failure
Killing the Simulator app does not fix xcodebuild

You quit or force-kill Simulator.app, but xcodebuild and simctl stay wedged — the hang survives killing the app.

Strong fit Likely: wrong process killed / CoreSimulatorService persistence

Shared state & cleanup

Stale device state, contaminated artifacts, and concurrent processes colliding over shared tooling.

DerivedData contamination between iOS test runs

Test runs interfere through shared DerivedData, result bundles, or logs — you get stale builds, overwritten .xcresult, or results from the wrong run.

Strong fit Likely: shared artifacts / DerivedData contamination
Simulator fails after a previous test run

The first run is fine, but the next test run on the same simulator fails or hangs — state from the previous run leaked into this one.

Strong fit Likely: stale device state between runs
Multiple xcodebuild processes on the same Mac

Several xcodebuild/simctl processes run at once on one Mac and start colliding over simulators, destinations, and build state.

Strong fit Likely: concurrent process contention / shared-state collisions
fastlane scan hangs after tests finish

All tests pass, but fastlane scan never exits — it hangs after the last test during teardown, result-bundle writing, or simulator shutdown.

Partial fit Likely: post-test teardown / result-bundle / simulator shutdown stall
fastlane scan hangs with parallel testing

fastlane scan or xcodebuild hangs once parallel testing spins up multiple simulator clones that contend for the simulator subsystem.

Partial fit Likely: parallel clone contention / CoreSimulator overload

CI-like workflow failures

Symptoms specific to CI and CI-like runner environments on a Mac.

No devices found for the iOS simulator in CI

A CI or CI-like Mac job fails with no iOS simulator devices found for the destination, even though it works on a developer machine.

Partial fit Likely: destination availability in runner environments
GitHub Actions iOS simulator job hangs

An iOS test job on a macOS runner hangs at simulator boot or destination resolution and eventually hits the job timeout.

Partial fit Likely: runner simulator boot/resolution stall

Coding-agent amplified failures

Failures that surface or worsen when coding agents drive test runs on a shared Mac.

Coding agents running iOS simulator tests on one Mac

Coding agents and scripts run xcodebuild/Simulator tests concurrently on one Mac, and runs start colliding, wedging, and failing unpredictably.

Strong fit Likely: concurrent simulator contention / shared-state collisions
AI coding agent hits xcodebuild timeouts

A coding agent running iOS tests keeps hitting xcodebuild timeouts or hangs — frequently because its runs collide with other simulator activity.

Strong fit Likely: agent-driven contention / unbounded runs

18 failure modes and counting.