dotnet/maui · critical · InvalidOperationException

call Forms.Init() before this

Error message

call Forms.Init() before this

What it means

PageExtensions.CreateViewController throws InvalidOperationException("call Forms.Init() before this") when Forms.IsInitialized is false. Embedding a Page into a native UIViewController requires the Forms platform (renderers, registrar) to be initialized first via Forms.Init().

Source

Thrown at src/Compatibility/Core/src/iOS/PageExtensions.cs:14

using System;
using System.Linq;
using ObjCRuntime;
using UIKit;

namespace Microsoft.Maui.Controls.Compatibility
{
	[System.Obsolete]
	public static class PageExtensions
	{
		public static UIViewController CreateViewController(this Page page)
		{
			if (!Forms.IsInitialized)
				throw new InvalidOperationException("call Forms.Init() before this");

			if (!(page.RealParent is Application))
			{
				Application app = new EmbeddedApplication();
				app.MainPage = page;
			}

			var result = new Platform.iOS.Platform();
			result.SetPage(page);
			return result.ViewController;
		}

		sealed internal class EmbeddedApplication : Application, IDisposable
		{
			public void Dispose()
			{
				CleanUp();
			}

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Call Forms.Init() in FinishedLaunching before any CreateViewController usage.
2. Guard with Forms.IsInitialized check and initialize on demand if needed.
3. Ensure the correct platform-specific Forms.Init overload (with the renderer assemblies) is invoked.

Example fix

// before
var vc = page.CreateViewController();
// after
if (!Forms.IsInitialized)
    Forms.Init();
var vc = page.CreateViewController();

if (!Forms.IsInitialized)
    Forms.Init();
var vc = page.CreateViewController();

When it happens

Trigger: Calling PageExtensions.CreateViewController() before Forms.Init() in the AppDelegate or before any Forms startup; using PageExtensions in a non-Forms hosted context.

Common situations: Integrating a single Forms Page into a native iOS app but forgetting Forms.Init() in FinishedLaunching; calling CreateViewController from a different startup path that runs before initialization; library code that assumes Forms is up.

Related errors

• You MUST invoke LoadApplication () before calling base.Finis
• Implement INativeElementView on cell renderer: {ContentCell.
• No UIViewController found to present.
• application
• InsertPageBefore is not supported globally on iOS, please us

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