Fix: In Xcode, go to Settings → Components, download Metal Toolchain, quit Xcode, then relaunch Unreal Editor.
From the terminal, xcodebuild -downloadComponent MetalToolchain works too. The same fix applies when the error comes back after an Xcode upgrade.
After a long break I tried to launch Unreal Engine 5.6.1 and Xcode showed Xcode Metal Compiler error — confusing at first.
Xcode Metal Compiler error: error: error: cannot execute tool 'metal due to
missing Metal Toolchain; use: xcodebuild -downloadComponent MetalToolchainHere’s what fixed it for Mac UE5 development.
A helpful thread: Stack Overflow — MetalToolchain.

Update (2026-09-27): Same error again on Xcode 27 × UE 5.8
After updating to Xcode 27, I tried to launch UE 5.8 and hit the exact same error.
“Not this again” — I’m guessing I’m not the only one.
I followed the steps in this post and it fixed it again.
Here’s the splash-screen version of the dialog:

After an Xcode upgrade, re-download Metal Toolchain with the steps below — same fix still works.
Why this happens
Starting with Xcode 16, Apple split the Metal Toolchain (the tools that compile .metal shaders) out of the main Xcode.app bundle to keep its download size down. It’s now downloaded separately, on demand, instead of shipping inside Xcode from the start.
After you upgrade Xcode, the same dialog can show up again — you’ll need to download the Toolchain for that version.
UE5 compiles Metal shaders internally as part of the build, so if the Toolchain hasn’t been downloaded yet, the build stops with this error.
In other words, this isn’t really a UE5 bug — it’s UE5’s build process running into Apple’s newer, split-out distribution model for Xcode components.
Fix Xcode Metal Compiler error
Step 1: Download Metal Toolchain in Xcode
- Launch Xcode
- Xcode → Settings → Components (or Settings depending on version)
- Click Download Metal Toolchain (whatever version number is shown)

The exact version number (26.x.x, 27.x.x, etc.) depends on your Xcode version.
Step 2: Wait for download to finish
When done, you should see a checkmark or completion indicator next to Metal Toolchain.

Step 3: Launch UE5 again
- Quit Xcode
- Start the Unreal Editor
- The Metal Compiler error should be gone
On my machine I didn’t need to reboot macOS or UE5 — closing Xcode and launching the editor from the Epic Launcher was enough.
If it still doesn’t work
- Run
xcodebuild -downloadComponent MetalToolchaindirectly from the terminal instead of the Settings UI - Check whether your Xcode version and command line tools (
xcode-select -p) actually match - On restricted networks (corporate, university), the download itself can stall — try a different network if it hangs
UE5 and Xcode together take a lot of storage on a Mac. If space is tight, an external SSD for projects and caches is one way out.
A Kioxia SSD is one option. Prices have been volatile with AI demand, so compare price and capacity before buying.