Troubleshooting 6 Known Issues in .NET MAUI

Let’s check out six of the most common problems that occur in .NET MAUI and how to solve them.

In the world of software development, it’s quite common to encounter challenges that we don’t know how to solve instantly. Whether you’re an experienced developer or simply taking your first steps in development, it’s all part of the process.

But don’t worry! In this article, we’ll explore six of the most common problems that occur in .NET MAUI and, most importantly, how to solve them. 🛠️ It’s about learning and growing together! Let’s get started and explore these solutions! 🚀📚

1. Platform Version Isn’t Present

Are you having trouble loading workloads in Visual Studio? Do not worry! This is fixed very quickly!

Sometimes, Visual Studio may not automatically resolve workloads when compiling a project, which can slow down your development progress. How can you identify if this is the issue you’re encountering? Typically, you would see a message like the following:

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

What is the root cause of this issue? 🤔

This problem typically arises when both the x86 and x64 versions of the SDK are installed, with the x86 version being used. For optimal functioning of Visual Studio and .NET MAUI, the .NET x64 SDK is required.

How can it be resolved?

Check if the system-wide PATH variable in your operating system favors the x86 SDK. To fix this, either remove the x86 .NET SDK from the PATH variable or adjust the settings so the x64 .NET SDK is prioritized.

For a detailed guide on distinguishing and troubleshooting issues between the x86 and x64 SDKs in Windows, refer to the “Install .NET on Windows: Troubleshooting” section.

2. Type or Namespace ‘Default’ Doesn’t Exist When Using the Contacts API

When working with the Contacts API on iOS or macOS platforms, you may sometimes encounter the following error message:

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

What causes this issue? 🤔

On both iOS and macOS platforms, there exists a root namespace named “Contacts”. This can lead to conflicts with the “Contacts” namespace found within the Microsoft.Maui.ApplicationModel.Communication. This particular namespace from Microsoft.Maui is automatically imported into your project due to the <ImplicitUsings> setting in the project file. This overlap can cause issues due to the namespace duplication.

What’s the solution?

To resolve this conflict, you should use the fully qualified name for the Contacts type. Alternatively, you can add a using directive at the beginning of your code file to explicitly map the namespace, as follows:

using Communication = Microsoft.Maui.ApplicationModel.Communication;

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

3. Xcode Isn’t Currently Installed or Couldn’t Be Found

Occasionally, after installing Xcode command-line tools using xcode-select --install, Visual Studio for Mac may show the message: “Xcode is not currently installed or could not be found.” This typically occurs when you try to create .NET MAUI applications targeting iOS or Mac Catalyst.

How can this be fixed?

To fix this issue, follow these steps:

1. Make sure Xcode is installed from the App Store.
2. Open Xcode, navigate to Xcode ➡️ Preferences ➡️ Locations. In the Command Line Tools section, check if the dropdown menu is set.
3. If the dropdown is empty, click it and select the appropriate Xcode Command Line Tools location.
4. Close Xcode and restart Visual Studio for Mac.

4. Duplicate Image Filename Errors

Starting from .NET 8, .NET MAUI has implemented checks to prevent duplicate resource file names, including icons and images. This rule applies to files that have the Build Action set to MauiImage and MauiIcon.

One or more duplicate file names were detected. All image output filenames must be unique.

Sometimes this could also happen with files with identical names but different extensions in different folders. For example, if there’s a PNG file named ”flowers.png” in Resources/Images/PNG/ and an SVG file with the same name in Resources/Images/SVG/, a compilation error will occur. This is due to the conversion of SVG files to PNG during the build process.

An error will also occur if you use the Include attribute on a MauiImage element to include all images in a folder, while also including a specific image file, as I show below:

<MauiImage Include="Resources\Images\*" /> 
<MauiImage Include="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

What’s the solution?

➖ To prevent this issue, make sure that your project does not contain any duplicate names for images and icons.

➖ For any MauiIcon or MauiImage referencing a specific file, use the Update attribute rather than the Include attribute. This adjustment can help avoid conflicts.

<MauiImage Include="Resources\Images\*" />
<MauiImage Update="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

5. Xcode Version Can’t Be Located

In some instances, when creating a .NET MAUI application for iOS or Mac Catalyst, you might unknowingly use a version of Xcode that’s no longer installed. This mismatch will prompt Visual Studio for Mac to display a notification, indicating the need to update or reinstall the correct version of Xcode. The message you receive will typically state the following:

xcodebuild: error: SDK "/Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" cannot be located.

xcrun: error: sh -c '/Applications/Xcode_14.1.app/Contents/Developer/usr/bin/xcodebuild -sdk /Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk -find dsymutil 2> /dev/null' failed with exit code 16384: (null) (errno=Invalid argument)

xcrun: error: unable to find utility "dsymutil", not a developer tool or in PATH

How to solve it?

It’s a simple fix! All you need to do is go to the following file:

~/Library/Preferences/Xamarin/Settings.plist

And specify the version of Xcode currently installed on your computer. This step ensures that your development environment is aligned with the correct version of Xcode, facilitating smoother project compilation and execution.

6. Can’t Locate the .NET MAUI Workloads

There are two main methods for installing .NET MAUI workloads:

• On Windows, Visual Studio can utilize .msi files to install each workload package.
• Alternatively, you can use dotnet workload installation commands.

However, there’s a cautionary note for Windows users: If you initiate a .NET workload installation after already installing .NET MAUI through the Visual Studio installer, you may encounter conflicts with the placement of .NET MAUI workloads. These conflicts often appear as build errors, wrongly suggesting that .NET MAUI workload installations are needed. Moreover, the workloads may become irreparable or non-reinstallable in these situations.

Solutions

Mac: The installation and upgrade process for Visual Studio on Mac depends on the dotnet workload installation commands to deploy .NET MAUI .pkg files. As .pkg files can’t be uninstalled, the best way to remove these workloads on a Mac is by running commands to delete specific directories. The commands you’ll need are as follows:

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

Windows: To properly uninstall .NET MAUI workloads, you’ll need to use a combination of the Command Line Interface (CLI), Control Panel and settings within Visual Studio. This process involves first uninstalling the workloads through the CLI, then removing the .NET SDKs via the Control Panel and, finally, managing the .NET MAUI workloads directly in Visual Studio. Follow these steps to accomplish this:

1. Execute the command dotnet workload uninstall maui if you’ve previously used dotnet workload install commands.
2. From the Control Panel, remove any independent .NET SDK installations. Look for installers with names resembling “Microsoft .NET SDK 6.0.300.”
3. For each Visual Studio instance, ensure to uninstall the .NET Multi-platform App UI development and “.NET desktop development” workloads.

Let’s check if there are additional .msi files, you can uninstall them with the following command:

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

You can also check the .NET 6+ SDKs that are still installed on your computer and use the reg query command, 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 a similar output, copy the GUID for each package and use the msiexec command to uninstall the package.

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

⚠️ You should persistently execute the reg query command until all components are fully uninstalled.

Following this, for a thorough cleanup, delete the following directories within the C:\Program Files\dotnet path:

• sdk-manifests
• metadata
• packs
• library-packs
• template-packs
• sdk\6.* or sdk\7.*
• host\fxr\6.* or host\fxr\7.*

You are now ready to reinstall .NET MAUI! 💕

Conclusion

That’s all! I hope that going forward, if you encounter these problems, you’ll know how to solve them. See you next time! 💚💕

References

This article was based on the official documentation:

• https://learn.microsoft.com/en-us/dotnet/maui/troubleshooting?view=net-maui-8.0