How to Fix “cannot execute tool ‘metal’ due to missing Metal Toolchain” in Xcode

Projects that compile Metal shaders, including Unreal Engine projects, can stop in Xcode 27 with cannot execute tool 'metal' due to missing Metal Toolchain. In a reported Xcode 27.0 case, the suggested download command also remained at Beginning asset download.... This guide follows Apple’s supported component workflow and separates confirmed installation steps from unconfirmed workarounds.

Representative error
Cause
Affected conditions and versions
Recommended steps
Alternatives when the download stalls
How to verify the result
Cautions
Summary
Official references

Representative error

error: error: cannot execute tool 'metal' due to missing Metal Toolchain;
use: xcodebuild -downloadComponent MetalToolchain

Beginning asset download...

xcodebuild: error: Download was cancelled.
(Asset download for com.apple.MobileAsset.MetalToolchain ...)

Cause

The active Xcode developer environment cannot locate a usable Metal Toolchain component. A result from xcrun --find metal only locates the launcher; it does not prove that the separately delivered compiler payload is available.

In the Xcode 27.0 forum report, component retrieval remained at Beginning asset download.... Apple has not confirmed a root cause or fixed release for that report. Do not assume without evidence that the network, free storage, Apple’s delivery service, or local component state is solely responsible.

Affected conditions and versions

Xcode 27.0 with the Metal Toolchain unavailable or not installed
Projects that compile .metal source files
Build systems such as Unreal Engine that invoke the Metal compiler
xcodebuild -downloadComponent MetalToolchain remaining at its initial message

As of September 28, 2026, the forum report has no reply and Apple has not published a confirmed fixed version for this specific stall.

Recommended steps

Verify the active Xcode installation.

xcode-select -p
xcodebuild -version

If multiple installations exist, select the intended Xcode.

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

Complete first-launch setup.
```
sudo xcodebuild -runFirstLaunch
```
Install from Xcode.
Open Xcode Settings, select Components, locate Metal Toolchain, and install it. This also tests whether only CLI retrieval is affected.
Download from the command line.
```
xcodebuild -downloadComponent MetalToolchain
```
Close Xcode and confirm sufficient free space and a stable connection. Avoid repeatedly cancelling after only a short wait.

Use Apple’s export/import workflow for another Mac or offline installation.

xcodebuild -downloadComponent metalToolchain -exportPath ~/Downloads
xcodebuild -importComponent metalToolchain -importPath /path/to/exported/component

Pass the actual exported file or directory to -importPath.

Alternatives when the download stalls

Check Apple Developer System Status and retry later
Compare another permitted network if a VPN, proxy, or filter is present
Compare Xcode Settings > Components with the CLI result
Export on another Mac and import with Apple’s supported command
Temporarily use a previously verified Xcode environment if practical

These options isolate or bypass the problem. They are not an Apple-confirmed permanent fix for the Xcode 27.0 download stall.

How to verify the result

xcrun metal --version

Confirm that valid version information appears. Then clean and rebuild the project and verify that CompileMetalFile succeeds. Because xcrun --find metal can succeed while the payload is missing, test both the version command and a real Metal build.

Cautions

Adding sudo does not repair a service-side or network problem.
Do not manually remove files under /System or internal MobileAsset locations.
Installing Command Line Tools is not the same as installing Metal Toolchain.
Ensure installation and the build use the same developer directory.
Until Apple identifies a fixed version, an upgrade is not a guaranteed remedy.

Summary

cannot execute tool 'metal' due to missing Metal Toolchain means the active Xcode environment cannot use the additional Metal compiler component. Verify xcode-select, then install through Xcode Settings or xcodebuild -downloadComponent. If retrieval stalls, use Apple’s export/import workflow or compare another permitted network and a previously working Xcode installation.