Overview
When using Xcode 26 on CircleCI, you might encounter an error related to the Metal toolchain: error: cannot execute tool 'metal' due to missing Metal Toolchain; use: xcodebuild -downloadComponent MetalToolchain This issue is a known problem with the Xcode 26, affecting all users, including those on local machines and other CI/CD platforms.
Prerequisites
Access to CircleCI with a project configured to use Xcode 26.
Basic understanding of executing commands in a CI/CD environment.
Solution
To work around the missing Metal Toolchain issue, follow these steps:
Download the Metal Toolchain: Run the following command to download the Metal Toolchain:
xcodebuild -downloadComponent metalToolchain -exportPath /tmp/MetalExport/
Modify the Export Metadata: Use the
sedcommand to adjust the export metadata:sed -i '' -e 's/17A5295f/17A5241e/g' /tmp/MetalExport/MetalToolchain-17A5295f.exportedBundle/ExportMetadata.plist
Import the Metal Toolchain: Finally, import the modified Metal Toolchain:
xcodebuild -importComponent metalToolchain -importPath /tmp/MetalExport/MetalToolchain-17A5295f.exportedBundle
These steps should be executed before the build step where the error occurs.