What causes "ContentLoader" in dotnet/maui?

Always assign a non-null IContentLoader (e.g. new FormsContentLoader()) to FormWindow.ContentLoader.

dotnet/maui · error · ArgumentNullException

ContentLoader

Error message

ContentLoader

What it means

FormWindow.OnContentLoaderChanged is a WPF DependencyProperty property-changed callback that throws ArgumentNullException("ContentLoader") when the new value is null. The FormWindow requires a non-null IContentLoader to load page content; a null binding breaks window content resolution.

Source

Thrown at src/Compatibility/Core/src/WPF/Controls/FormWindow.cs:179

		{
			if (CurrentFlyoutPage != null)
			{
				CurrentFlyoutPage.IsPresented = !CurrentFlyoutPage.IsPresented;
			}
		}

		private void PreviousButton_Click(object sender, RoutedEventArgs e)
		{
			if (CurrentNavigationPage != null && CurrentNavigationPage.StackDepth > 1)
			{
				CurrentNavigationPage.OnBackButtonPressed();
			}
		}

		private static void OnContentLoaderChanged(DependencyObject o, DependencyPropertyChangedEventArgs e)
		{
			if (e.NewValue == null)
				throw new ArgumentNullException("ContentLoader");
		}

		public void SynchronizeAppBar()
		{
			IEnumerable<FormsPage> childrens = this.FindVisualChildren<FormsPage>();

			CurrentTitle = childrens.FirstOrDefault()?.GetTitle();
			HasNavigationBar = childrens.FirstOrDefault()?.GetHasNavigationBar() ?? false;
			CurrentNavigationPage = childrens.OfType<FormsNavigationPage>()?.FirstOrDefault();
			CurrentFlyoutPage = childrens.OfType<FormsFlyoutPage>()?.FirstOrDefault();
			var page = childrens.FirstOrDefault();
			if (page != null)
			{
				TitleBarBackgroundColor = page.GetTitleBarBackgroundColor();
				TitleBarTextColor = page.GetTitleBarTextColor();
			}
			else
			{

View on GitHub (pinned to f377ff1c5e)

Solutions

Always assign a non-null IContentLoader (e.g. new FormsContentLoader()) to FormWindow.ContentLoader.
If using a binding, ensure the source property never returns null, or use FallbackValue.
In cleanup, dispose the loader rather than nulling the property.
Validate resource keys for {StaticResource}/{DynamicResource} ContentLoader assignments.

Example fix

// before
<controls:FormWindow ContentLoader="{Binding Loader}" />

// after
<controls:FormWindow ContentLoader="{Binding Loader, FallbackValue={x:Static local:FormsContentLoader.Default}}" />

Defensive patterns

Strategy: validation

Validate before calling

if (loader == null) throw new InvalidOperationException("ContentLoader must be set before use");
window.ContentLoader = loader ?? new FormsContentLoader();

Type guard

static bool HasValidLoader(FormWindow w) => w.ContentLoader != null;

Try / catch

try { window.ContentLoader = candidate; }
catch (ArgumentNullException) { window.ContentLoader = new FormsContentLoader(); }

Prevention

Always assign a concrete FormsContentLoader/DefaultContentLoader in XAML or code-behind.
Use FallbackValue on ContentLoader bindings to avoid null resolution.
Never null the property during teardown; dispose underlying content instead.

When it happens

Trigger: Setting FormWindow.ContentLoader (via XAML or code) to null; a binding to ContentLoader that resolves to null because the source or DataContext is unset; a StaticResource/DynamicResource for the loader that fails to resolve.

Common situations: XAML assigns ContentLoader through a binding whose path returns null; resource key typo so {StaticResource} fails; cleanup code sets ContentLoader to null during teardown; swapping loaders without keeping a default instance.

Related errors

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