Fix `xcodebuild` Destination Errors by Selecting an Installed Simulator

Ask the scheme what it can build for

xcodebuild may reject a destination string when the simulator runtime is not installed, the device type is unavailable for that Xcode version, or the selected scheme does not support the requested platform. Start from the project and scheme that CI actually uses:

xcodebuild -list -workspace ios/Runner.xcworkspace
xcodebuild -showdestinations -workspace ios/Runner.xcworkspace -scheme Runner

Copy a valid destination identifier from the output rather than assuming a model name is stable across Xcode releases. For CI, pin Xcode and choose an available generic destination when a specific simulator model is not required.

Separate missing runtime from scheme configuration

Check installed runtimes with xcrun simctl list runtimes. If the runtime is missing, install it through the approved Xcode component process. If it exists but does not appear for the scheme, inspect the scheme's supported platforms, target settings, and workspace selection.

Avoid -destination 'platform=iOS Simulator,name=iPhone ...' values copied from another machine without verifying availability. Device names can change, and multiple devices may share a display name. Use the identifier in automation when the environment is controlled.

After selecting a destination, run a small build or test command and keep the exact Xcode version and destination in CI logs. A destination error occurs before application code runs, so changing Swift sources or deleting DerivedData is unlikely to solve a missing runtime. Make the runner's simulator inventory part of the build assumptions and fail early with a readable diagnostic.

Build a destination diagnostic

Start with the project or workspace and the scheme that the failing command actually uses. xcodebuild -showdestinations reports destinations valid for that scheme, while a general simulator list reports devices that may not support the target. Compare platform, runtime, architecture, and availability state. A simulator can be installed but unavailable because its runtime is missing, its device type is unsupported by the selected Xcode, or another process is using it.

Prefer a UDID in automation when the runner inventory is controlled. Names are readable but can be duplicated, renamed, or absent on another Xcode image. If a job intentionally chooses by name, print the resolved UDID and fail when more than one match exists. Do not silently choose the first device returned by a list command; that makes a destination failure intermittent when the runner image changes.

Keep CI inventory explicit

Pin the Xcode image and install the runtime required by the scheme. At job start, log xcodebuild -version, the available runtimes, and the selected destination. If the runtime is absent, fail in provisioning with an actionable message rather than allowing application compilation to obscure the environment problem. A destination error happens before source code executes, so changing Swift or Flutter code is not an appropriate first response.

After correcting the destination, run a small build or test and then the complete command. Record whether the simulator was newly created, booted from a snapshot, or already running. This context matters for UI tests and permissions. Keep destination selection separate from test logic so a new simulator model can be added without rewriting every test command.

Add a preflight that lists installed runtimes, device types, and destinations valid for the selected scheme. Compare the requested runtime with the target deployment floor and Xcode version. If a destination is unavailable, report valid choices without silently switching to another OS. A silent fallback can make tests pass against the wrong platform and leave a release-specific issue undiscovered. Use a UDID when names can collide and log whether the device was created, booted, or restored from a snapshot.

If a requested model is not installed, do not substitute a different model without recording the change. Device type can affect safe-area geometry, OS behavior, and UI test timing. For a stable CI contract, provision the runtime and device type in the runner image, then validate them before starting tests. When multiple Xcode versions exist, ensure xcrun and xcodebuild use the same selected developer directory. Keep the preflight output with failed test artifacts: requested destination, resolved UDID, runtime, architecture, and availability. Do not allow a runner to pick an arbitrary booted device.

If a requested model is not installed, report the closest valid destinations but require an explicit decision before changing the test matrix. Device type affects safe-area geometry, OS behavior, keyboard layout, and UI timing. A silent fallback can make a test pass on an easier platform while the intended release runtime remains untested. Provision the Xcode image, simulator runtime, and device type together, and fail before application tests when that contract is not met.