Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Xcode 26 will not compile Metal shaders because the Metal Toolchain is missing

ErrorA build fails on .metal files and Xcode asks you to download the Metal Toolchain

Short answer

Since Xcode 26 the Metal Toolchain is an optional component that is not installed with Xcode. Any target with .metal files, including Core Image kernels and some game or camera packages, fails until you install it. Get it in Xcode Settings under Components, or run xcodebuild -downloadComponent metalToolchain.

  • Applies to Xcode 26, macOS 26
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the active Xcode where its metal compiler is. If the command prints a path and the build still fails, skip to the last cause.

    xcode-select -p
    xcrun -f metal
  2. 2Match what you see, then jump to its fix

    1. 1The build fails on the first .metal file and xcrun -f metal finds no toolThe Metal Toolchain component was never installedFix
    2. 2The download in Settings or Terminal never finishes, or the build machine has no access to Apple's serversThe Mac cannot download it (managed or offline machine, CI image)Fix
    3. 3Settings shows the toolchain as installed, yet xcodebuild or Xcode still reports the toolchain as unavailableThe toolchain is installed but this Xcode build does not find itFix

What does the error look like?

  • A build fails on .metal files and Xcode asks you to download the Metal Toolchain
  • Downloaded Metal Toolchain may appear unavailable in Xcode when building metal projects

Cause 1 of 3

The Metal Toolchain component was never installed

1Check

Open Xcode > Settings > Components and look under Other Components for Metal Toolchain. Apple describes the toolchain as optional: you download it for the platforms your app targets.

xcrun -f metal

2Fix

Click Get next to Metal Toolchain in Xcode > Settings > Components. If a dialog appears during a build, click Download. The same install works from Terminal.

xcodebuild -downloadComponent metalToolchain

3Verify

The tool path prints, then build again.

xcrun -f metal

Confirmed by developer.apple.com

Did this fix it?

Cause 2 of 3

The Mac cannot download it (managed or offline machine, CI image)

1Check

Decide which machine can reach Apple's servers. The component can be exported to a file on that machine and imported on the other one.

xcodebuild -downloadComponent metalToolchain -exportPath ~/Downloads

2Fix

Copy the exported disk image to the machine that cannot download, then import it into the Xcode that machine uses.

xcodebuild -importComponent metalToolchain ~/Downloads/metalToolchain.dmg

3Verify

Confirm the compiler is now found by the selected Xcode.

xcrun -f metal

Confirmed by developer.apple.com

Did this fix it?

Cause 3 of 3

The toolchain is installed but this Xcode build does not find it

1Check

Apple's Xcode 26 release notes list fixes for the downloaded toolchain showing as unavailable, for a stale xcrun cache after the download, and for xcodebuild not finding it on the command line. Compare your Xcode version with the latest 26.x.

xcodebuild -version
xcrun -f metal

2Fix

Install the newest Xcode 26.x, make sure the command-line tools point at it, and download the component again from Settings.

sudo xcode-select -s /Applications/Xcode.app

3Verify

Run the build from the command line and from Xcode.

xcodebuild -version && xcrun -f metal

Confirmed by developer.apple.com

Did this fix it?

How do I stop it coming back?

  • On a build server, add the component install (or an import of an exported copy) to the image setup, so every Xcode update is followed by the same step.
  • After switching Xcode versions with xcode-select, run xcrun -f metal once to confirm the compiler is found.
  • Keep Xcode on the latest 26.x release.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Mobile apps

App record creation fails because you lack permission

You cannot add a new app in App Store Connect as a Developer or limited user

Only the Account Holder, an Admin or an App Manager can create an app record, and Apple blocks it until the Account Holder has signed the latest agreement.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.