dotnet/maui · error · InvalidOperationException

Call Forms.Init() before this

Error message

Call Forms.Init() before this

What it means

PageExtensions.ToFrameworkElement throws InvalidOperationException("Call Forms.Init() before this") if Forms.IsInitialized is false. ToFrameworkElement builds the WPF platform backend (Platform, FormsApplicationPage) on demand, which requires the Forms application to have been initialised first via Forms.Init().

Source

Thrown at src/Compatibility/Core/src/WPF/Extensions/PageExtensions.cs:11

using System;
using System.Windows;

namespace Microsoft.Maui.Controls.Compatibility.Platform.WPF.Extensions
{
	public static class PageExtensions
	{
		public static FrameworkElement ToFrameworkElement(this Page view)
		{
			if (!Forms.IsInitialized)
				throw new InvalidOperationException("Call Forms.Init() before this");

			if (!(view.RealParent is Application))
			{
				Application app = new DefaultApplication
				{
					MainPage = view
				};

				var formsApplicationPage = new FormsApplicationPage();
				formsApplicationPage.LoadApplication(app);
				var platform = new Platform(formsApplicationPage);
				platform.SetPage(view);
			}

			IVisualElementRenderer renderer = Platform.GetOrCreateRenderer(view);

			if (renderer == null)
			{

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Call Forms.Init() in the WPF application's OnStartup / Main before any ToFrameworkElement call.
2. For unit tests or designers, call Forms.Init() in a setup method or guard the call with Forms.IsInitialized.
3. Centralise Forms initialisation in one place and ensure it runs on the UI thread before Page use.
4. If embedding in an existing app, hook Application.Startup rather than a Page constructor.

Example fix

// before
protected override void OnStartup(StartupEventArgs e)
{
    var fe = page.ToFrameworkElement();
    ...
}

// after
protected override void OnStartup(StartupEventArgs e)
{
    Forms.Init();
    var fe = page.ToFrameworkElement();
    ...
}

if (!Forms.IsInitialized) Forms.Init();
return page.ToFrameworkElement();

static bool FormsReady => Forms.IsInitialized;

try { return page.ToFrameworkElement(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Forms.Init"))
{ Forms.Init(); return page.ToFrameworkElement(); }

When it happens

Trigger: Calling ToFrameworkElement on a Page before invoking Forms.Init() in the WPF host's startup; calling it from a designer, unit test, or static constructor that runs before the host's Main initialises Forms.

Common situations: WPF host that wires Pages before Forms.Init(); designer-time instantiation; reordered startup where the first ToFrameworkElement runs ahead of the Init call; multiple entry points (CLI/designer) that skip Init.

Related errors

• Cannot navigate to FormsEmbeddedPageWrapper without providin
• Could not find or create a renderer for the Page {page}
• call Forms.Init() before this
• Unable to find the required services. Please add all the req
• RootComponent requires a value for its Selector property, bu

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