dotnet/maui · error · InvalidOperationException

Could not find or create a renderer for the Page {page}

Error message

Could not find or create a renderer for the Page {page}

What it means

Thrown as InvalidOperationException by FormsEmbeddedPageWrapper.OnNavigatedTo when page.CreateFrameworkElement() returns null. This means no renderer could be found or created for the ContentPage. The renderer infrastructure (Registrar) must have a handler registered for the page's type, and Forms must be initialized.

Source

Thrown at src/Compatibility/Core/src/Windows/PageExtensions.cs:38

			base.OnNavigatedTo(e);

			if (e.Parameter == null)
			{
				throw new InvalidOperationException($"Cannot navigate to {nameof(FormsEmbeddedPageWrapper)} without "
					+ $"providing a {nameof(Microsoft.Maui.Controls.Page)} identifier.");
			}

			// Find the page instance in the dictionary and then discard it so we don't prevent it from being collected
			var key = (Guid)e.Parameter;
			var page = Pages[key];
			Pages.Remove(key);

			// Convert that page into a FrameWorkElement we can display in the ContentPresenter
			FrameworkElement frameworkElement = page.CreateFrameworkElement();

			if (frameworkElement == null)
			{
				throw new InvalidOperationException($"Could not find or create a renderer for the Page {page}");
			}

			Root.Content = frameworkElement;
		}
	}

	[System.Obsolete]
	public static class PageExtensions
	{
		public static FrameworkElement CreateFrameworkElement(this ContentPage contentPage)
		{
			return contentPage.ToFrameworkElement();
		}

		internal static FrameworkElement ToFrameworkElement(this VisualElement visualElement)
		{
			if (!Forms.IsInitialized)
			{

View on GitHub (pinned to f377ff1c5e)

Solutions

Add an ExportRenderer attribute mapping the custom Page type to its renderer.
Call Forms.Init() with all required renderer assemblies before embedding pages.
Verify the page type is not stripped by linker/trimming settings.

Example fix

// before — CustomPage has no renderer registered
FormsEmbeddedPageWrapper.Pages[guid] = new CustomPage();
Frame.Navigate(typeof(FormsEmbeddedPageWrapper), guid);

// after
[assembly: ExportRenderer(typeof(CustomPage), typeof(CustomPageRenderer))]
// and ensure Forms.Init includes the assembly

Defensive patterns

Strategy: validation

Validate before calling

if (Forms.IsInitialized && Registrar.Registered.GetHandlerForObject<IVisualElementRenderer>(page) != null)
    var fe = page.CreateFrameworkElement();

Prevention

Register all custom Page renderers via ExportRenderer attributes.
Ensure Forms.Init() runs with the correct assembly list before embedding pages.
Check linker/trimmer settings don't strip renderer types.

When it happens

Trigger: Calling CreateFrameworkElement on a page whose renderer type is not registered with the Registrar, or when Forms initialization is incomplete so GetOrCreateRenderer returns null.

Common situations: Using a custom Page subclass without a corresponding ExportRenderer attribute; calling embedding APIs before all renderer assemblies have been registered via Forms.Init; or assembly stripping/removing the renderer during build.

Related errors

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