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().

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

• call Forms.Init() before this
• Cannot navigate to FormsEmbeddedPageWrapper without…
• Could not find or create a renderer for the Page
• ' ' Transition could not be found!
• Activity OnCreate was not called prior to loading the…

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

Appendix: 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)