dotnet/maui · error · InvalidOperationException

call Forms.Init() before this

Error message

call Forms.Init() before this

What it means

Thrown as InvalidOperationException by PageExtensions.ToFrameworkElement when Forms.IsInitialized is false. The embedding API (CreateFrameworkElement / ToFrameworkElement) needs the full Forms infrastructure — registrar, platform services, renderers — to be bootstrapped via Forms.Init() before any page can be platformed.

Source

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

			}

			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)
			{
				throw new InvalidOperationException("call Forms.Init() before this");
			}

			var root = new Microsoft.UI.Xaml.Window();

			// Yes, this looks awkward. But the page needs to be Platformed or several things won't work
			new WindowsPlatform(root);

			var renderer = visualElement.GetOrCreateRenderer();

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

			var frameworkElement = renderer.ContainerElement;

			frameworkElement.Loaded += (sender, args) =>
			{

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Call Forms.Init() (or Forms.Init(assemblyList)) at application startup before any CreateFrameworkElement call.
2. If using FormsApplicationPage, ensure its OnStartup/Initialize completes before embedding pages.
3. Add a guard: check Forms.IsInitialized before calling ToFrameworkElement.

Example fix

// before
var fe = contentPage.CreateFrameworkElement(); // throws

// after
if (!Forms.IsInitialized)
    Forms.Init();
var fe = contentPage.CreateFrameworkElement();

if (!Forms.IsInitialized)
    Forms.Init();
var fe = contentPage.CreateFrameworkElement();

When it happens

Trigger: Calling contentPage.CreateFrameworkElement() or visualElement.ToFrameworkElement() before Forms.Init() has been called in the application's startup sequence.

Common situations: Calling embedding APIs from a non-standard entry point (e.g., a library constructor, a static initializer, or a design-time preview) before the application has run its Forms.Init bootstrap. Also when embedding is used outside a FormsApplicationPage lifecycle.

Related errors

• Cannot navigate to FormsEmbeddedPageWrapper without providin
• Could not find or create a renderer for the Page {page}
• Call Forms.Init() before this
• NavigationStack is not supported globally on Windows, please
• PushAsync is not supported globally on Windows, please use a

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