When a .NET MAUI iOS or Mac Catalyst build fails on a Mac, check the toolchain in order: confirm the SDK, workload and target framework; make sure the required full Xcode installation is selected; build for the platform you intend to test; then deploy to a simulator or provisioned iOS device. The Xcode version required depends on the MAUI release, so check Microsoft’s current setup requirements rather than relying on a fixed version pairing.
1. Record the SDK, workload and project target
Before changing installations or settings, capture the versions and target involved. This helps distinguish a compatibility problem from a bad Xcode selection or a build aimed at the wrong platform.
- Run
dotnet --versionfrom the project environment to see the active .NET SDK. - Check the project file for its target framework and confirm the matching MAUI workload is installed.
- Record the macOS and Xcode versions, then compare them with the requirements for your .NET MAUI release. Microsoft’s MAUI setup guidance and CLI workflow point to release-specific requirements.
Do not assume an example target framework from an older tutorial matches a newer project. The CLI tutorial includes older net8.0-* examples; use a target framework supported by your installed SDK and declared by your project.
2. Resolve Xcode installation and selection errors
MAUI iOS and Mac Catalyst builds on macOS require a compatible full Xcode installation. Installing only Apple’s command-line tools does not provide the documented environment. Install the Xcode version required for your MAUI release, open Xcode to complete first-run setup, accept its license, and install the simulator runtime you need through Xcode Settings/Components.
#1 Best Overall
- SUPERCHARGED BY M5 — The 14-inch MacBook Pro with M5 brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. Featuring all-day battery life and a breathtaking Liquid Retina XDR display with up to 1600 nits peak brightness, it’s pro in every way.*
- HAPPILY EVER FASTER — Along with its faster CPU and unified memory, M5 features a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR APPLE INTELLIGENCE — Apple Intelligence is the personal intelligence system that helps you write, express yourself, and get things done effortlessly. With groundbreaking privacy protections, it gives you peace of mind that no one else can access your data — not even Apple.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.
- APPS FLY WITH APPLE SILICON — All your favorites, including Microsoft 365 and Adobe Creative Cloud, run lightning fast in macOS.*
“Xcode is not currently installed or could not be found”
Check that Xcode is installed and that Xcode’s Command Line Tools setting points to the intended installation. A command-line-tools-only setup is not a substitute for full Xcode for these targets. See Microsoft’s macOS troubleshooting guidance.
“Could not find a valid Xcode app bundle”
Inspect which developer directory is active:
xcode-select -pIf the result points to an obsolete or invalid installation, select the installed Xcode, adjusting the app name if yours differs:
sudo xcode-select --switch /Applications/Xcode.app/Contents/DeveloperMicrosoft also documents xcode-select --reset as a remedy for an invalid app-bundle selection. For a single terminal session, you can select Xcode with DEVELOPER_DIR instead:
Rank #2
- FAST RUNS IN THE FAMILY — The 16-inch MacBook Pro with the M5 Pro or M5 Max chip brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. With all-day battery life, double the starting storage,* and a breathtaking Liquid Retina XDR display, it’s pro in every way.*
- BUCKLE UP — Along with a next-generation CPU, faster unified memory, and up to 2x faster SSD storage,* M5 Pro and M5 Max feature a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance and on-device training capabilities. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR AI — Apple silicon, and every major component that powers it, is designed to run demanding on-device AI workloads like LLM inference and training. And Apple Intelligence helps you write, express yourself, and get things done effortlessly with groundbreaking privacy protections at every step.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.*
- MACOS RUNS APPS FAST — All your go-to apps run lightning fast in macOS, including built-in apps like FaceTime and Messages. Plus, built-in virus protection and free software updates help keep your Mac running smoothly and securely.
export DEVELOPER_DIR=/Applications/Xcode.app/Contents/DeveloperOlder Xamarin/MAUI settings plist files and MD_APPLE_SDK_ROOT can affect Xcode resolution, but Microsoft describes these legacy mechanisms as deprecated and recommends xcode-select or DEVELOPER_DIR. More details are in the Microsoft troubleshooting page and CLI guidance.
“Xcode version can’t be located”
First verify that the selected developer directory is the intended Xcode and that the installed Xcode is supported by your MAUI release. Recheck xcode-select -p and the Xcode Command Line Tools selection in Xcode; selecting a valid but incompatible Xcode version will not resolve a release-compatibility issue.
3. Build for the platform you are actually testing
iOS and Mac Catalyst are different targets. From the project directory, pass the target framework for the platform you want to build, using the framework declared by your project. For example, a project targeting .NET 10 may use:
Rank #3
- FAST RUNS IN THE FAMILY — The 16-inch MacBook Pro with the M5 Pro or M5 Max chip brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. With all-day battery life, double the starting storage,* and a breathtaking Liquid Retina XDR display, it’s pro in every way.*
- BUCKLE UP — Along with a next-generation CPU, faster unified memory, and up to 2x faster SSD storage,* M5 Pro and M5 Max feature a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance and on-device training capabilities. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR AI — Apple silicon, and every major component that powers it, is designed to run demanding on-device AI workloads like LLM inference and training. And Apple Intelligence helps you write, express yourself, and get things done effortlessly with groundbreaking privacy protections at every step.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.*
- MACOS RUNS APPS FAST — All your go-to apps run lightning fast in macOS, including built-in apps like FaceTime and Messages. Plus, built-in virus protection and free software updates help keep your Mac running smoothly and securely.
net10.0-iosfor iOSnet10.0-maccatalystfor Mac Catalyst
These are examples, not universal values: target frameworks change with SDK releases. Confirm the project’s supported targets and use Microsoft’s CLI build guidance for the installed release. The CLI workflow can restore, build and run the app with dotnet build -t:Run; specify the appropriate framework with -f when needed.
“Platform version is not present for one or more target frameworks”
This wording appears in Microsoft’s troubleshooting material, but its illustrated platform-version resolution case concerns Windows SDK resolution. It is not, by itself, a macOS-specific instruction to reinstall Xcode. Identify which target framework and platform the error actually names before applying a fix; see the troubleshooting examples.
Recommended Free Tools
If compilation succeeds but packaging fails
Errors naming images, splash screens, fonts or duplicate image filenames point to asset packaging rather than necessarily to Xcode or the compiler. Match the remedy to the specific asset error in Microsoft’s MAUI troubleshooting guide instead of repeatedly reinstalling Xcode.
Rank #4
- SUPERCHARGED BY M5 — The 14-inch MacBook Pro with M5 brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. Featuring all-day battery life and a breathtaking Liquid Retina XDR display with up to 1600 nits peak brightness, it’s pro in every way.*
- HAPPILY EVER FASTER — Along with its faster CPU and unified memory, M5 features a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR APPLE INTELLIGENCE — Apple Intelligence is the personal intelligence system that helps you write, express yourself, and get things done effortlessly. With groundbreaking privacy protections, it gives you peace of mind that no one else can access your data — not even Apple.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.
- APPS FLY WITH APPLE SILICON — All your favorites, including Microsoft 365 and Adobe Creative Cloud, run lightning fast in macOS.*
4. Run and debug in an iOS simulator
A simulator requires its runtime to be installed in Xcode. Once installed, build and run with the iOS target framework and select the simulator destination through the workflow you use. The .NET CLI can run a target with dotnet build -t:Run -f <ios-TFM>; substitute the iOS target framework declared by your project. Microsoft’s CLI tutorial documents the command-line flow.
Simulator deployment is a separate path from deploying to a physical device. A simulator is useful for iterative development, but it cannot reproduce every hardware-dependent behavior.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.5. Deploy to a provisioned iOS device
Physical-device deployment requires provisioning as well as a connection to the Mac. Connect the device, then find its UDID in Xcode under Window > Devices and Simulators. Microsoft’s device deployment instructions use an iOS arm64 runtime identifier and the device UDID:
Best Value
- SUPERCHARGED BY M5 — The 14-inch MacBook Pro with M5 brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. Featuring all-day battery life and a breathtaking Liquid Retina XDR display with up to 1600 nits peak brightness, it’s pro in every way.*
- HAPPILY EVER FASTER — Along with its faster CPU and unified memory, M5 features a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR APPLE INTELLIGENCE — Apple Intelligence is the personal intelligence system that helps you write, express yourself, and get things done effortlessly. With groundbreaking privacy protections, it gives you peace of mind that no one else can access your data — not even Apple.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.
- APPS FLY WITH APPLE SILICON — All your favorites, including Microsoft 365 and Adobe Creative Cloud, run lightning fast in macOS.*
dotnet build -t:Run -f <ios-TFM> -p:RuntimeIdentifier=ios-arm64 -p:_DeviceName=<UDID>Replace <ios-TFM> with the iOS framework used by the project and <UDID> with the connected device’s identifier. Provisioning and signing details vary by project and account; this command does not replace those requirements.
6. Choose the right debugging destination
| Area | Simulator | Physical iOS device |
|---|---|---|
| Setup | Install the needed simulator runtime in Xcode. | Connect the device and provision the app. |
| Target selection | Choose an available simulator destination and use the project’s iOS target framework. | Use the device UDID with RuntimeIdentifier=ios-arm64. |
| What it can reveal | Convenient iteration in a simulated environment. | Device-specific behavior, including effects of hardware constraints such as memory or network connectivity. |
Microsoft recommends physical-device testing because some behavior depends on real hardware; simulators and devices therefore serve different purposes rather than replacing one another. See the device testing guidance.
When the toolchain checks pass but the app still fails
Once the SDK, workload, selected Xcode and target framework are aligned, use the actual diagnostic to narrow the next step. Asset-specific packaging errors have a different cause from Xcode resolution errors. App-specific compiler failures, third-party library problems, account-specific signing setup and debugger behavior depend on the project and tooling details; the toolchain checks above do not identify those automatically.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
