macOS runner: iOS simulator runtime not available / needs download in CI

By Kaveh Alemi·Latchkey

The test targets a simulator runtime (an iOS version) that the runner image does not ship. Recent Xcode versions download runtimes on demand, so CI must install the runtime before it can boot a matching device.

What this error means

xcodebuild fails with "Unable to find a destination matching the provided destination specifier" or simctl reports the runtime as "(not installed)" / "unavailable, runtime not found".

-- iOS 17.5 --
    iPhone 15 (unavailable, runtime profile not found)
xcodebuild: error: Unable to find a destination matching the provided destination specifier:
        { platform:iOS Simulator, OS:17.5, name:iPhone 15 }

Common causes

The requested runtime is not installed on the image

Each runner image ships a fixed set of simulator runtimes. Targeting an iOS version outside that set leaves no matching destination.

A new runtime must be downloaded first

On recent Xcode, runtimes are downloadable components; until you download one, devices for that iOS version are unavailable.

How to fix it

Download the runtime, then target it

1. List installed runtimes with xcrun simctl runtime list.
2. Download the missing iOS runtime.
3. Re-run targeting an installed OS version.

xcrun simctl list runtimes
xcodebuild -downloadPlatform iOS
xcrun simctl list runtimes

Target a runtime the image already ships

Pick a destination OS version that is preinstalled so no download is needed.

xcodebuild test -scheme App \
  -destination 'platform=iOS Simulator,name=iPhone 15,OS=latest'

How to prevent it

• Use OS=latest or an installed runtime to avoid downloads.
• List runtimes before selecting a destination.
• Download required runtimes explicitly in a setup step.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions