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 MacCatalyst sample loads an SF Symbol system image named 'macwindow.badge.plus' to use as a navigation bar button icon. UIImage.GetSystemImage returns null if the symbol name does not exist on the running OS version. The code throws InvalidOperationException to surface the missing asset immediately rather than passing null to UIBarButtonItem and crashing later.

Source

Thrown at src/Controls/samples/Controls.Sample.Embedding/Platforms/MacCatalyst/MainViewController.cs:85

		stackView.AddArrangedSubview(thirdButton);

		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

View on GitHub (pinned to f377ff1c5e)

Solutions

Provide a fallback image when the symbol is unavailable: `var icon = UIImage.GetSystemImage("macwindow.badge.plus") ?? UIImage.GetSystemImage("plus.app");`
Verify the symbol exists on your minimum deployment target using the SF Symbols app.
Use a custom bundled image asset as a guaranteed fallback.

Example fix

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

// after
var windowIcon = UIImage.GetSystemImage("macwindow.badge.plus")
    ?? UIImage.GetSystemImage("plus.app")
    ?? UIImage.FromBundle("FallbackAddWindow");

Defensive patterns

Strategy: fallback

Validate before calling

var windowIcon = UIImage.GetSystemImage("macwindow.badge.plus")
    ?? UIImage.GetSystemImage("plus.app")
    ?? UIImage.FromBundle("FallbackAddWindow");
if (windowIcon is null)
    return; // skip nav button if no icon available

Prevention

Verify SF Symbol availability against your minimum macOS deployment target using the SF Symbols app.
Always provide a fallback image for system symbols.
Bundle a custom asset as a guaranteed cross-version fallback.

When it happens

Trigger: Running the sample on a macOS/macOS Catalyst version where the 'macwindow.badge.plus' SF Symbol was not yet introduced or has been renamed. Apple occasionally adds, renames, or deprecates SF Symbols across OS versions.

Common situations: Deploying to older macOS versions that predate the symbol's introduction. Xcode/Symbol availability mismatch between development and target runtime. Apple renaming symbols between major OS releases (e.g., macOS 13 to 14).

Related errors

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