dotnet/maui · error · InvalidOperationException

Unable to load system image 'macwindow.badge.plus'

Error message

Unable to load system image 'macwindow.badge.plus'

What it means

This iOS sample loads the SF Symbol 'macwindow.badge.plus' for a navigation bar button. UIImage.GetSystemImage returns null if the symbol is unavailable on the running iOS version. The code throws InvalidOperationException because passing null to UIBarButtonItem would cause a later crash. Note: this symbol is macOS/macOS Catalyst oriented and may not exist on iPhone/iPad.

Source

Thrown at src/Controls/samples/Controls.Sample.Embedding/Platforms/iOS/MainViewController.cs:86

		if (UIDevice.CurrentDevice.UserInterfaceIdiom == UIUserInterfaceIdiom.Pad)
			AddNavBarButtons();
	}

	private async void OnMagicClicked(object? sender, EventArgs e)
	{
		if (_mauiView?.DotNetBot is not Image bot)
			return;

		await bot.RotateToAsync(360, 1000);
		bot.Rotation = 0;

		bot.HeightRequest = 90;
	}

	private void AddNavBarButtons()
	{
		var windowIcon = UIImage.GetSystemImage("macwindow.badge.plus") ?? throw new InvalidOperationException("Unable to load system image 'macwindow.badge.plus'");

		var addNewWindowButton = new UIBarButtonItem(
			windowIcon,
			UIBarButtonItemStyle.Plain,
			(sender, e) => RequestSession());

		var addNewTaskButton = new UIBarButtonItem(
			UIBarButtonSystemItem.Add,
			(sender, e) => RequestSession("NewTaskWindow"));

		NavigationItem.RightBarButtonItems = [addNewTaskButton, addNewWindowButton];
	}

	private void RequestSession(string? activityType = null)
	{
		var activity = activityType is null
			? null
			: new NSUserActivity(activityType);

View on GitHub (pinned to f377ff1c5e)

Solutions

Use an iOS-available symbol or provide a fallback: `var icon = UIImage.GetSystemImage("macwindow.badge.plus") ?? UIImage.GetSystemImage("plus.circle");`
Bundled a custom image asset as a guaranteed fallback for cross-platform samples.
Conditionally choose symbols based on platform (UIDevice.CurrentDevice.UserInterfaceIdiom).

Example fix

// before
var windowIcon = UIImage.GetSystemImage("macwindow.badge.plus")
    ?? throw new InvalidOperationException(...);

// after
var symbolName = UIDevice.CurrentDevice.UserInterfaceIdiom == UIUserInterfaceIdiom.Pad
    ? "macwindow.badge.plus" : "plus.app";
var windowIcon = UIImage.GetSystemImage(symbolName)
    ?? UIImage.FromBundle("FallbackAddWindow");

Defensive patterns

Strategy: fallback

Validate before calling

var symbolName = UIDevice.CurrentDevice.UserInterfaceIdiom == UIUserInterfaceIdiom.Pad
    ? "macwindow.badge.plus" : "plus.app";
var windowIcon = UIImage.GetSystemImage(symbolName)
    ?? UIImage.FromBundle("FallbackAddWindow");
if (windowIcon is null)
    return;

Prevention

Use platform-appropriate SF Symbols — 'macwindow.badge.plus' is macOS-oriented.
Provide an iOS-compatible fallback symbol or bundled asset.
Conditionally select symbols based on UIDevice.CurrentDevice.UserInterfaceIdiom.

When it happens

Trigger: Running the iOS sample on a device or simulator where 'macwindow.badge.plus' does not exist (it is primarily a macOS Catalyst symbol). The symbol may be entirely absent from iOS SF Symbol sets.

Common situations: Running a MacCatalyst-oriented sample on iOS where the symbol was never available. Apple restricting certain symbols to macOS-only. Deploying to older iOS versions.

Related errors

AI-assisted analysis of dotnet/maui@f377ff1c5e (2026-08-13). Data as JSON: /api/errors/b683eef34155063c. Report an issue: GitHub.