Can XCSteward help with "xcodebuild destination unavailable or ineligible"?

This is a partial fit. XCSteward may help when the failure comes from execution readiness, destination selection, timeouts, cleanup, or contention. It probably will not help when the root cause is missing configuration, a broken runtime, a test-code bug, or a vendor image defect.

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 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 class: destination matching / device eligibility · Updated 2026-06-08

xcodebuild unable to find a device matching the destination
xcodebuild ineligible destinations
xcodebuild destination unavailable
Ineligible destinations for scheme
Unable to find a destination matching the provided destination specifier
requested device could not be found simulator

Symptom

xcodebuild does not hang — it fails fast with a destination error and never starts testing. The message says it cannot find a device matching your -destination, or it lists your intended device under “Ineligible destinations”.

What it usually looks like

Common messages:

xcodebuild: error: Unable to find a device matching the provided destination specifier: followed by your specifier.
The requested device could not be found because no available devices matched the request.
An Ineligible destinations for the "<scheme>" scheme: block listing a device with a reason (missing runtime, wrong platform, unavailable).
It works on one machine and fails on another with the “same” Xcode.

This is different from xcodebuild hanging while resolving a destination: here you get a clear error rather than an open-ended stall.

Why it happens / likely failure classes

The destination specifier did not match a usable device. Typical causes:

The named device does not exist in this Xcode’s device set (different device name, or it was deleted).
The runtime is missing or not installed for that device — common after an Xcode update or on a fresh machine. (If the runtime is genuinely absent, this is an environment problem, not an execution one.)
Wrong or ambiguous specifier — a typo, a stale UDID, or OS= pinned to a version you do not have installed.
The device is in an unavailable state (corrupt, or its runtime was removed) so it is filtered out of the eligible set.
xcode-select points at a different Xcode than the one whose simulators you expect.

Quick checks

# What devices and runtimes actually exist for the selected Xcode?
xcrun simctl list devices available
xcrun simctl list runtimes

# What does Xcode consider a valid destination for your scheme?
xcodebuild -showdestinations -scheme YourScheme -workspace YourApp.xcworkspace

# Are you pointed at the Xcode you think you are?
xcode-select -p

If simctl list runtimes does not include the OS you are targeting, the destination is unavailable because the runtime is missing — install it before anything else.

Manual mitigations

Target a concrete device by UDID that you confirmed is available:

xcrun simctl list devices available     # copy a UDID
xcodebuild test -scheme YourScheme \
  -destination "platform=iOS Simulator,id=<UDID>"

Create the device if the name/runtime combo you want is missing:
```
xcrun simctl create "iPhone 16" "iPhone 16" "iOS18.2"
```
Install the missing runtime (recent Xcode):
```
xcodebuild -downloadPlatform iOS
```
Prune unavailable devices so eligibility is computed against a clean set:
```
xcrun simctl delete unavailable
```

When XCSteward may help

This is a partial fit. XCSteward is designed to run against a concrete, verified destination, so it can:

Resolve and pin a known-available device up front, and surface a clear “this destination is not available” result before a run, rather than letting an implicit specifier fail mid-pipeline.
Run a readiness check that confirms the chosen device exists and is bootable, so eligibility problems show up as an early, legible failure.

It is worth testing against this class of failure when the destination exists but keeps getting selected inconsistently across runs.

When XCSteward probably will not help

If the runtime is simply not installed, you need to install it — XCSteward will tell you the destination is unavailable sooner, but it cannot download a runtime for you.
If your specifier targets a device/OS that does not exist in your setup, that is a configuration fix, not an execution one.
It does not change Xcode’s eligibility rules or repair a corrupt install.

Common questions

What does "xcodebuild destination unavailable or ineligible" usually mean?: It usually points to destination matching / device eligibility. xcodebuild errors out that the destination is unavailable or ineligible — no device matches the specifier — instead of running 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 destination unavailable or ineligible"?: This is a partial fit. XCSteward may help when the failure comes from execution readiness, destination selection, timeouts, cleanup, or contention. It probably will not help when the root cause is missing configuration, a broken runtime, a test-code bug, or a vendor image defect.
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.