dotnet/maui · critical · InvalidOperationException

Please provide a main window in your app

Error message

Please provide a main window in your app

What it means

In DidFinishLaunching the host requires a non-null MainWindow before it can Display() and make it key. On macOS the main window normally comes from the storyboard/MainWindow.xib; if it is null the app has nothing to render into and throws InvalidOperationException. This is a host-configuration requirement, not an application-logic error.

Source

Thrown at src/Compatibility/Core/src/MacOS/FormsApplicationDelegate.cs:43

		protected void LoadApplication(Application application)
		{
			if (application == null)
				throw new ArgumentNullException(nameof(application));

			Application.SetCurrentApplication(application);
			_application = application;

			if (NSApplication.SharedApplication.MainMenu != null)
				_storyboardMainMenuCount = (int)NSApplication.SharedApplication.MainMenu.Count;

			application.PropertyChanged += ApplicationOnPropertyChanged;
		}

		public override void DidFinishLaunching(Foundation.NSNotification notification)
		{
			if (MainWindow == null)
				throw new InvalidOperationException("Please provide a main window in your app");

			MainWindow.Display();
			MainWindow.MakeKeyAndOrderFront(NSApplication.SharedApplication);
			if (_application == null)
				throw new InvalidOperationException("You MUST invoke LoadApplication () before calling base.FinishedLaunching ()");

			SetMainPage();
			UpdateMainMenu();
			_application.SendStart();
		}

		public override void DidBecomeActive(Foundation.NSNotification notification)
		{
			// applicationDidBecomeActive
			// execute any OpenGL ES drawing calls
			if (_application == null || !_isSuspended)
				return;
			_isSuspended = false;

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Ensure the app delegate's MainWindow outlet is connected to a window in the main storyboard, or assign it in code before DidFinishLaunching.
2. If building the window in code, construct and assign MainWindow in the delegate constructor or WillFinishLaunching.
3. Verify the storyboard's initial view controller is a window controller and the outlet is bound.

Example fix

// before (code-built, window never set)
public override void DidFinishLaunching(NSNotification n)
{
    // MainWindow is null -> throws
    base.DidFinishLaunching(n);
}

// after
public override void DidFinishLaunching(NSNotification n)
{
    MainWindow = new NSWindow(...);
    base.DidFinishLaunching(n);
}

if (MainWindow == null)
    throw new InvalidOperationException("Configure MainWindow before launch");
base.DidFinishLaunching(notification);

When it happens

Trigger: DidFinishLaunching runs with MainWindow == null. Happens when the storyboard lacks a main window, the window outlet is not connected, or a code-built app forgot to assign MainWindow before the launching callback.

Common situations: New macOS project missing the default MainWindow.storyboard wiring. Storyboard outlet for the window deleted/disconnected. Headless/test invocation of the delegate without a window.

Related errors

• You MUST invoke LoadApplication () before calling base.Finis
• call Forms.Init() before this
• application
• NavigationPage must have a root Page before being used. Eith
• You MUST invoke LoadApplication () before calling base.Finis

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