Edit

Troubleshooting known issues

  • Article
  • 4 minutes to read

This article describes some of the known issues with .NET Multi-platform App UI (.NET MAUI), and how you can solve or work around them. The .NET MAUI repository also details some known issues.

Can't locate the .NET MAUI workloads

There are two options for installing the .NET MAUI workloads:

  1. Visual Studio on Windows can install .msi files for each workload pack.
  2. dotnet workload install commands.

On Windows, if you run a dotnet workload install after installing .NET MAUI through the Visual Studio installer, Visual Studio can enter a state where it can't locate the .NET MAUI workloads. You'll then receive build errors telling you to install the .NET MAUI workloads, and it's possible to enter a state where the workloads can't be repaired or re-installed. For more information about this issue, see The CLI and VS do not play nicely.

Windows

The solution to this issue on Windows is to uninstall the .NET MAUI workloads through the CLI, uninstall any .NET SDKs in Control Panel, and uninstall the .NET MAUI workloads in Visual Studio. This can be accomplished with the following process:

  1. Run dotnet workload uninstall maui if you ever used the dotnet workload install commands.
  2. Uninstall any standalone .NET SDK installers from Control Panel. These will have names similar to Microsoft .NET SDK 6.0.300.
  3. In every instance of Visual Studio, uninstall the .NET Multi-platform App UI development, and .NET desktop development Visual Studio workloads.

Then, check if there are additional .msi files that need uninstalling by running the following command:

reg query HKLM\SOFTWARE\Microsoft\Windows\currentversion\uninstall\ -s -f manifest

This reg query command will list .NET 6+ SDKS that are still installed on your machine, such as:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\currentversion\uninstall\{EEC1BB5F-3391-43C2-810E-42D78ADF3140}
    InstallSource    REG_SZ    C:\ProgramData\Microsoft\VisualStudio\Packages\Microsoft.MacCatalyst.Manifest-6.0.300,version=125.179.40883,chip=x64,productarch=neutral\
    DisplayName    REG_SZ    Microsoft.NET.Sdk.MacCatalyst.Manifest-6.0.300

If you receive similar output, you should copy the GUID for each package and uninstall the package with the msiexec command:

msiexec /x {EEC1BB5F-3391-43C2-810E-42D78ADF3140} /q IGNOREDEPENDENCIES=ALL

Then, you should keep executing the reg query command until it doesn't return any results. Once this happens, and all .NET 6+ SDKs are uninstalled, you should also consider deleting the following folders:

  • C:\Program Files\dotnet\sdk-manifests
  • C:\Program Files\dotnet\metadata
  • C:\Program Files\dotnet\packs
  • C:\Program Files\dotnet\library-packs
  • C:\Program Files\dotnet\template-packs
  • C:\Program Files\dotnet\sdk\6.* or C:\Program Files\dotnet\sdk\7.*
  • C:\Program Files\dotnet\host\fxr\6.* or C:\Program Files\dotnet\host\fxr\7.*

After following this process, you should be able to re-install .NET MAUI either through Visual Studio, or by installing your chosen .NET SDK version and running the dotnet workload install maui command.

Mac

Visual Studio for Mac's installer and updater uses dotnet workload install commands to install the .NET MAUI .pkg files.

Since .pkg files can't be uninstalled, the simplest approach to uninstalling the workloads on a Mac is to run the following commands to delete the specified folders:

rm -r ~/.dotnet/
sudo rm -r /usr/local/share/dotnet/

After executing these commands, you should be able to re-install .NET MAUI either through Visual Studio for Mac, or by installing your chosen .NET SDK version and running dotnet workload install maui command.

Platform version isn't present

Visual Studio may not be resolving the required workloads if you try to compile a project and receive an error similar to the following text:

Platform version is not present for one or more target frameworks, even though they have specified a platform: net6.0-android, net6.0-ios, net6.0-maccatalyst

Platform version is not present for one or more target frameworks, even though they have specified a platform: net7.0-android, net7.0-ios, net7.0-maccatalyst

This problem typically results from having an x86 and x64 SDK installed, and the x86 version is being used. Visual Studio and .NET MAUI require the x64 .NET SDK. If your operating system has a system-wide PATH variable that is resolving the x86 SDK first, you'll need to fix that by either removing the x86 .NET SDK from the PATH variable, or promoting the x64 .NET SDK so that it resolves first. For more information on troubleshooting x86 vs x64 SDK resolution, see Install .NET on Windows - Troubleshooting.

Type or namespace 'Default' does not exist

When using the Contacts API, you may see the following error related to iOS and macOS:

The type or namespace name 'Default' does not exist in the namespace 'Contacts' (are you missing an assembly reference?)

The iOS and macOS platforms contain a root namespace named Contacts. This conflict causes a conflict for those platforms with the Microsoft.Maui.ApplicationModel.Communication namespace, which contains a Contacts type. The Microsoft.Maui.ApplicationModel.Communication namespace is automatically imported by the <ImplicitUsings> setting in the project file.

To write code that also compiles for iOS and macOS, fully qualify the Contacts type. Alternatively, provide a using directive at the top of the code file to map the Communication namespace:

using Communication = Microsoft.Maui.ApplicationModel.Communication;

// Code that uses the namespace:
var contact = await Communication.Contacts.Default.PickContactAsync();

Xcode isn't currently installed or couldn't be found

After installing the Xcode command line tools, using xcode-select --install, Visual Studio for Mac might show a "Xcode is not currently installed or could not be found" message when attempting to build .NET MAUI apps that target iOS or Mac Catalyst. In this scenario, check that you also have Xcode installed from the App Store. Then, launch Xcode and go to Xcode > Preferences > Locations > Command Line Tools and check if the drop-down is empty. If it is empty, select the drop-down and then select the location of the Xcode command line tools. Then close Xcode and restart Visual Studio for Mac.

Couldn't find a valid Xcode app bundle

If you receive the error "Could not find a valid Xcode app bundle at '/Library/Developer/CommandLineTools'", when attempting to build .NET MAUI apps that target iOS or Mac Catalyst, you should try the solution described in Xcode isn't currently installed or couldn't be found. If you're still unable to access the Xcode > Preferences > Locations > Command Line Tools drop-down, run the following command:

sudo xcode-select --reset