What does "xcodebuild timed out waiting for the simulator" usually mean?

It usually points to boot/readiness timeout. xcodebuild aborts with a timeout waiting for the simulator to boot or to be ready, instead of running the tests. Start by checking simulator readiness, destination selection, CoreSimulator/simctl responsiveness, and whether another xcodebuild, simctl, or Simulator process is already active before treating it as a test-code failure.

Can XCSteward help with "xcodebuild timed out waiting for the simulator"?

This is a strong fit when the failure is operational: simulator readiness, destination resolution, CoreSimulator responsiveness, cleanup, timeouts, or local concurrency. XCSteward may help by making those phases bounded, serialized, and easier to inspect. It will not fix broken tests, code signing, missing runtimes, or vendor image bugs.

What should I check first?

Check whether xcrun simctl commands return promptly, whether xcodebuild can resolve a concrete simulator destination, whether the device is truly ready rather than merely Booted, and whether concurrent agents, scripts, or manual runs are touching the same simulator subsystem.

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 class: boot/readiness timeout · Updated 2026-06-09

xcodebuild timed out waiting for simulator
timed out waiting for the simulator to boot
timed out waiting for simulator to be ready
xcodebuild failed to boot simulator timeout
xcodebuild simulator boot timeout
failed to background test runner timeout simulator

Symptom

The run gets far enough to start bringing up a simulator, then xcodebuild gives up with a timeout — it waited for the device to boot or become ready and the deadline passed before that happened.

What it usually looks like

Errors mentioning a timeout: Timed out waiting for ... to boot, Timed out waiting for the simulator to be ready, or a test-runner launch that times out.
The device may be left in Booting and never reaches Booted.
The build can complete, but the runner still never starts or attaches before the environment deadline.
In XCSteward terms, if the timeout hits before it observes XCTest attach/test execution evidence, the result stays runner_bootstrap_failure with diagnostic_excerpt.subtype = pre_xctest_timeout, not plain test_timeout.
It is intermittent — slower on the first run after a reboot, Xcode update, or runtime install, and more likely when the machine is busy.
Bumping a launch/boot timeout sometimes “fixes” it, which is a sign the device was just slow to become ready, not broken.

Why it happens / likely failure classes

A boot or readiness step did not finish inside the allotted time:

Cold start cost. First boot after a reboot/update warms a lot of state and can exceed a default timeout.
Device never finishes booting — stuck in Booting, often because the subsystem underneath is slow or wedged. See unable to boot the simulator.
CoreSimulator under load or contention. Other simulator work happening at the same time stretches boot/readiness past the deadline. See multiple xcodebuild processes on one Mac.
Resource pressure (CPU, RAM, disk) slowing the boot enough to trip the timeout.
Implicit boot during the run — letting xcodebuild boot the device as part of the run gives it less slack than booting ahead of time.

Quick checks

# Boot it yourself and time how long it actually takes to be ready
time (xcrun simctl boot <UDID>; xcrun simctl bootstatus <UDID> -b)

# Is it stuck in Booting, or does it reach Booted?
xcrun simctl list devices | grep -i 'boot'

# Anything else hammering the subsystem while you boot?
pgrep -lf 'xcodebuild|simctl|Simulator'

If a manual boot takes longer than the timeout your run allows, the device is simply slow to become ready — that is the thing to address.

Manual mitigations

Boot ahead of time and block on readiness, then run against the already booted device:

xcrun simctl boot <UDID>
xcrun simctl bootstatus <UDID> -b      # waits until boot completes
xcodebuild test-without-building \
  -scheme YourScheme \
  -destination "platform=iOS Simulator,id=<UDID>"

Warm the device with a throwaway launch so the test run is not paying the cold-start cost.
Run one simulator job at a time so boot is not competing for the subsystem.
Free up resources (close other simulators, check disk space) before a run.
If the device repeatedly will not finish booting, erase and recreate it.

When XCSteward may help

Bounding and verifying the boot/readiness window is a core design goal:

Deterministic boot + readiness checks that wait for the device to be genuinely ready before handing off to xcodebuild, rather than racing an implicit boot against a timeout.
A single execution lane so a boot is not slowed by other simulator activity, which is a common reason readiness misses the deadline.
Clear timeouts with recovery so a device that truly will not boot fails fast and is reset, instead of repeatedly timing out mid-run.
Compact wait/watch output for humans, plus --json, --progress, status <job-id> --watch --json, and explain <job-id> --json for agents that need a stable outcome and evidence path.
Pre-XCTest bootstrap diagnosis: when the runner or environment setup fails before XCTest attaches, XCSteward reports runner_bootstrap_failure instead of making a timeout look like a normal test failure.
Clear timeout-before-attach detail: pre_xctest_timeout means the test command hit its timeout before XCSteward observed XCTest attach/test execution evidence. The summary says XCTest did not attach before the test command timed out, and terminal JSON may include phase, timeout seconds, evidence paths, and a capped diagnostic excerpt.
Bounded doctor preflight: the .xctestrun integrity timeout warning now says when no compiler error was observed before timeout, which is useful diagnosis for cold or long builds, not a promise to keep waiting indefinitely.

Worth testing against this class of failure, especially if timeouts cluster under load or after cold starts.

When XCSteward probably will not help

If a device is genuinely broken or its runtime is corrupt, you may need to erase/recreate it or reinstall the runtime.
It cannot make an underpowered or disk-starved machine boot faster beyond removing contention.
It does not change xcodebuild’s own internal timeouts or fix a defect in a specific simulator runtime.

Common questions

What does "xcodebuild timed out waiting for the simulator" usually mean?: It usually points to boot/readiness timeout. xcodebuild aborts with a timeout waiting for the simulator to boot or to be ready, instead of running the tests. Start by checking simulator readiness, destination selection, CoreSimulator/simctl responsiveness, and whether another xcodebuild, simctl, or Simulator process is already active before treating it as a test-code failure.
Can XCSteward help with "xcodebuild timed out waiting for the simulator"?: This is a strong fit when the failure is operational: simulator readiness, destination resolution, CoreSimulator responsiveness, cleanup, timeouts, or local concurrency. XCSteward may help by making those phases bounded, serialized, and easier to inspect. It will not fix broken tests, code signing, missing runtimes, or vendor image bugs.
What should I check first?: Check whether xcrun simctl commands return promptly, whether xcodebuild can resolve a concrete simulator destination, whether the device is truly ready rather than merely Booted, and whether concurrent agents, scripts, or manual runs are touching the same simulator subsystem.