Fix .NET MAUI Setup & Build Errors (2026 Guide)

Why .NET MAUI Breaks , And Why the Error Messages Don't Help

You've seen it. You fire up Visual Studio, create a brand-new .NET MAUI project targeting Android, iOS, macOS, and Windows from a single shared codebase , exactly what the framework promises, and then the build explodes with something like NETSDK1045, a missing workload, or a cryptic Xcode license error. You didn't touch anything. You followed the quickstart. And yet here you are.

I've seen this exact situation on dozens of developer machines, and the root causes almost always fall into a few predictable categories. Understanding which one you're hitting is the fastest path out.

Workload mismatch. .NET MAUI installs as a set of SDK workloads on top of the .NET runtime. If your .NET SDK version and your installed MAUI workload version are out of sync, say you updated the SDK via Windows Update or a standalone installer but didn't re-run dotnet workload restore, you'll get errors that look unrelated to what actually happened. Visual Studio's "Repair" button often doesn't fix this because it operates on the VS component, not the underlying SDK workloads.

Android SDK configuration drift. The .NET MAUI Android target requires specific Android SDK components, platform versions, and build tools. If you've upgraded Android Studio separately, changed the ANDROID_HOME environment variable, or installed multiple SDK instances, .NET MAUI's MSBuild integration loses track of what to use. The error messages it produces, things like "Unable to find android.jar" or a silent failure on dotnet build -t:Run -f net10.0-android, are genuinely misleading.

Single-project structure confusion. One of .NET MAUI's core design decisions is a single-project architecture where one .csproj targets multiple platforms through multi-targeting. That's elegant in theory but means your project file carries platform-specific MSBuild conditions, and when something's wrong with one target framework moniker (TFM), the error surfaces in ways that look like the whole project is broken. It's often just one TFM.

Xamarin migration residue. A huge proportion of the developers I talk to are migrating from Xamarin.Forms. The .NET Upgrade Assistant can handle a lot of the heavy lifting, but it leaves behind deprecated API calls, old NuGet package references, and XAML namespace prefixes that don't exist in .NET MAUI. Those don't always fail loudly, sometimes they just silently break data binding or cause app lifecycle events to fire in the wrong order.

Hot Reload and XAML Compilation fighting each other. .NET MAUI XAML is compiled at build time by default (XamlCompilation is opt-in per class but enabled globally in modern templates). When Hot Reload is active and you're also running XAML compilation, a stale compiled XAML type can conflict with the live-reloaded version, producing XamlParseException at runtime with a stack trace pointing at line 1 of every file.

I know how frustrating this is, especially when your deadline is tomorrow and you're stuck on tooling rather than writing actual app code. The good news is that every one of these is fixable. Browse all Microsoft fix guides →

The Quick Fix, Try This First

Before you spend an hour in the Android SDK Manager or start editing project files, run this sequence. It resolves the majority of .NET MAUI build failures caused by workload drift and corrupted local caches.

Open a terminal, either the Developer Command Prompt in Visual Studio or plain Windows Terminal, and run these three commands in order:

dotnet workload repair
dotnet workload update
dotnet nuget locals all --clear

Here's what each one actually does. dotnet workload repair re-installs the currently pinned workload versions from scratch, overwriting anything that got partially installed or corrupted. dotnet workload update pulls the latest compatible workload manifests for your SDK band. dotnet nuget locals all --clear wipes every local NuGet cache, the http-cache, the global packages folder, the temp folder, all of it. A corrupt or version-mismatched cached package is the silent killer of MAUI build pipelines.

After all three complete, close Visual Studio completely. Don't just close the project, close the IDE. Then reopen your solution and do a full rebuild with Build > Rebuild Solution. If you're on a Mac targeting iOS, also run sudo xcode-select --reset in Terminal before reopening Rider or VS for Mac.

This sequence fixes roughly 60–70% of the ".NET MAUI suddenly stopped building" cases I've handled. If you're still seeing errors after this, move to the step-by-step section, the remaining cases need more targeted surgery.

Advanced Troubleshooting, When the Standard Fixes Don't Work

If you've been through the five steps above and you're still hitting walls, these advanced techniques are where the real answers live. These apply especially to enterprise environments, CI/CD pipelines, and machines managed by Group Policy or MDM.

MSBuild binary log analysis. The single most useful debugging tool for stubborn .NET MAUI build failures is the MSBuild binary log. Run your build with:

dotnet build -f net10.0-android -bl:build.binlog

Then open build.binlog with the MSBuild Structured Log Viewer (free download from the MSBuild GitHub). This shows you the complete build graph, every target that ran, every property value, every imported SDK file. What looks like a cryptic one-line error in the terminal is almost always traceable to a specific MSBuild target that failed fifteen levels deep. I've diagnosed workload version mismatches, missing Android SDK components, and broken NuGet restore in under three minutes with this tool.

Multi-targeting isolation. In a .NET MAUI single project, you can temporarily disable platform TFMs to isolate which one is causing the problem. Open your .csproj and find the <TargetFrameworks> element. Comment out all but one TFM:

<TargetFrameworks>net10.0-android<!--;net10.0-ios;net10.0-maccatalyst;net10.0-windows10.0.19041.0--></TargetFrameworks>

Build against just Android. Then just iOS. This narrows down whether you have a framework-agnostic error (build fails on all TFMs) or a platform-specific one. Framework-agnostic errors are usually NuGet package incompatibilities or C# code that uses APIs not available in a particular TFM. Platform-specific errors point at SDK configuration.

Native AOT and trimming issues. If you're publishing with <PublishTrimmed>true</PublishTrimmed> or Native AOT enabled (which .NET MAUI supports as of .NET 9+), you may see runtime crashes that don't reproduce in Debug builds. These are trimming errors, the linker removed a type or method that's accessed via reflection. The fix is adding trimming annotations or a TrimmerRootDescriptor XML file. Check the official .NET MAUI trimming documentation for the descriptor format.

CI/CD and headless build environments. Building .NET MAUI in a CI pipeline (Azure DevOps, GitHub Actions) requires the workloads to be explicitly installed in the pipeline definition. The Visual Studio Installer doesn't run in CI. Add this to your pipeline YAML before the build step:

- script: dotnet workload install maui
  displayName: 'Install .NET MAUI workload'

Also pin your .NET SDK version using a global.json in the repo root, CI agents frequently have multiple SDK versions and will pick the wrong one without explicit pinning.

Xamarin migration residue, deep check. After running the .NET Upgrade Assistant, search your entire solution for these patterns that the assistant sometimes misses: Xamarin.Forms namespace references in XAML files, Device.RuntimePlatform (replaced by DeviceInfo.Platform), DependencyService.Get<T>() (replaced by .NET DI), and MessagingCenter (replaced by WeakReferenceMessenger from the .NET Community Toolkit). Any of these left in place will cause build warnings that turn into runtime failures.

Prevention & Best Practices, Keep .NET MAUI Builds Healthy

The developers who never seem to hit these problems aren't lucky, they've just built a set of habits that prevent the most common failure modes. Here's what I tell every team that's adopting .NET MAUI seriously.

Pin your SDK version. Add a global.json to your solution root the moment you start a new project. Specify the exact SDK version your project requires. This prevents the silent SDK upgrade problem where a developer's machine or CI agent gets a new SDK band that the installed workloads don't yet support.

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestPatch"
  }
}

latestPatch allows patch updates (security fixes) while blocking minor and major upgrades until you explicitly update the file. That's the right balance between security and stability.

Run workload updates as part of your sprint cadence. Don't let workloads drift for months. Once every two weeks, run dotnet workload update. Do it when you're not under deadline pressure. That way you catch breaking changes early when you have time to deal with them, rather than the night before a release.

Use the single-project structure as designed. Resist the temptation to add platform-specific projects back as separate .csproj files unless you have a very specific reason. The .NET MAUI single project with multi-targeting and the Platforms/ folder for platform-specific code handles the vast majority of use cases. Fighting the architecture costs more than it saves.

Test on real devices early. Emulators are great for iteration but they don't catch all platform-specific issues, especially around permissions, app lifecycle events when the OS terminates your app for memory, and platform-specific layout rendering. Add real device testing to your process from the first sprint, not the last.

Keep your XAML and C# in sync. MAUI's code-behind partial class pattern means your XAML and your C# file share a class. If you rename a control in XAML and forget to update the code-behind reference, you'll get a build error. It's obvious when it happens, but consistently using the IDE's rename refactoring (F2 in Visual Studio) instead of manual text edits prevents this class of error entirely.

Frequently Asked Questions