CommunityToolkit.Maui Causing Crash at Startup: `System.TypeLoadException`

After updating the CommunityToolkit.Maui NuGet Package, my app now crashes when the app launches with a System.TypeLoadException:

System.TypeLoadException: Could not set up parent class, due to: Invalid generic instantiation assembly:/Users/lars/Library/Developer/CoreSimulator/Devices/8A23F9D5-1BE5-4094-AEC5-712F50FEE6E5/data/Containers/Bundle/Application/98766B0A-DAAD-41A5-A8CA-72CE4010C2B1/CommunityToolkitCrash.app/Microsoft.Maui.dll type:ViewHandler`2 member:(null)
   at CommunityToolkit.Maui.AppBuilderExtensions.<>c.<UseMauiCommunityToolkit>b__0_0(IMauiHandlersCollection h)
   at Microsoft.Maui.Hosting.HandlerMauiAppBuilderExtensions.HandlerRegistration.AddRegistration(IMauiHandlersCollection builder)

I haven't changed any of my code. Is there a work-around for this?

Solution

.NET MAUI Community Toolkit Maintainer here.

We've recently had a flurry of similar Issues opened and, after delving into the problem, we've identified that the TypeLoadException is caused by a misconfiguration of your local developer environment.

Long story short, .NET MAUI is a workload in .NET and there's no way for our NuGet Package to verify or require that a specific .NET MAUI workload is installed on your machine. Yet, our NuGet package also requires you to be using the latest stable (non-preview) version of .NET + .NET MAUI.

Until Microsoft improves the .NET Workload developer experience, please ensure you are always using the latest stable (non-preview) releases of the .NET SDK, .NET MAUI, Visual Studio and Xcode:

[ ] Update Xcode
- As of today, the supported version of Xcode is 16.0.0
- Read the latest .NET MAUI Release wiki to always find the latest-supported version) of Xcode for .NET MAUI
- I HIGHLY recommend using the open-source tool Xcodes to easily manage your installed Xcode versions
[ ] Update to the latest stable version of Visual Studio (or Jet Brains Rider)
[ ] Download/install the latest stable (non-preview) version of the .NET SDK
[ ] After installing the latest stable .NET SDK, update to the latest stable version of the .NET MAUI workload
- On macOS, open the Terminal and enter the following command: sudo dotnet workload install maui
- On Windows, open the command prompt (or Powershell) and enter the following command: dotnet workload install maui
[ ] Add a global.json file to your application with the following parameters to ensure you're not using a unsupported preview version of .NET (example below)
- The .NET MAUI Community Toolkit does not support preview releases of .NET

global.json

{
  "sdk": {
    "version": "8.0.403", 
    "rollForward": "latestMajor",
    "allowPrerelease": false
  }
}