CircleCI macOS "Xcode version not available" - Fix

A macOS job requested an Xcode version CircleCI does not provide, or the macOS executor is not enabled for your plan. The job cannot provision the requested image.

What this error means

The macOS job fails to start, reporting the Xcode version is not available, or that macOS is not enabled for the org. iOS/macOS builds never begin.

CircleCI UI

Xcode version "15.99.0" is not available.
Available versions: 15.4.0, 15.3.0, 15.2.0, ...
# or
macOS executor is not enabled on your plan.

Common causes

Unsupported or retired Xcode version

The macos.xcode value must be a currently-provided image tag. Older versions are retired and brand-new ones may not be available yet.

macOS not enabled for the org

macOS executors require a plan that includes them. Without it, the executor cannot provision regardless of the Xcode tag.

Wrong resource class for macOS

macOS uses its own classes (e.g. macos.m1.medium.gen1). A Linux class name under a macOS executor is invalid.

How to fix it

Pin a supported Xcode image

.circleci/config.yml

jobs:
  ios-build:
    macos:
      xcode: 15.4.0
    resource_class: macos.m1.medium.gen1
    steps:
      - checkout
      - run: xcodebuild -version

Confirm macOS access and valid versions

Check the CircleCI macOS/Xcode support docs for currently-available tags.
Confirm your plan includes macOS executors.
Use a macOS-specific resource_class, not a Linux one.

How to prevent it

Pin a currently-supported Xcode tag and update it as versions retire.
Confirm macOS is enabled for the org before adding iOS jobs.
Use macOS resource classes for macOS executors.