unoplatform/uno · critical · InvalidOperationException

Main window must be initialized before Frame

Error message

Main window must be initialized before Frame

What it means

Thrown by InitializeFrame when the _mainWindow field is null. The method builds a Frame into the main window's content, so a null window means the app's initialization order skipped window creation before navigation setup.

Source

Thrown at src/SamplesApp/SamplesApp.Shared/App.xaml.cs:370

		}

		public event EventHandler? MainWindowActivated;

#if HAS_UNO && !HAS_UNO_WINUI
		protected override void OnWindowCreated(global::Microsoft.UI.Xaml.WindowCreatedEventArgs args)
		{
			if (Current is null)
			{
				throw new InvalidOperationException("The Window should be created later in the application lifecycle.");
			}
		}
#endif

		private void InitializeFrame(string? arguments = null)
		{
			if (_mainWindow is null)
			{
				throw new InvalidOperationException("Main window must be initialized before Frame");
			}

			var rootFrame = _mainWindow.Content as Frame;

			// Do not repeat app initialization when the Window already has content,
			// just ensure that the window is active
			if (rootFrame is null)
			{
				// Create a Frame to act as the navigation context and navigate to the first page
				rootFrame = new Frame();

				rootFrame.NavigationFailed += OnNavigationFailed;

				// Place the frame in the current Window
				_mainWindow.Content = rootFrame;
			}

			if (rootFrame.Content is null)

View on GitHub (pinned to 0418340488)

Solutions

1. Ensure _mainWindow is created (call EnsureWindowCreated/Activate) before InitializeFrame.
2. In OnLaunched, follow the documented order: create window -> activate -> initialize frame.
3. Guard InitializeFrame to create the window if null rather than throw, if late initialization is intentional.

Example fix

// before
private void InitializeFrame(string? arguments = null)
{
    if (_mainWindow is null)
        throw new InvalidOperationException("Main window must be initialized before Frame");
// after - ensure the window exists first
private void InitializeFrame(string? arguments = null)
{
    _mainWindow ??= EnsureWindowCreated();
    _mainWindow.Activate();

_mainWindow ??= EnsureWindowCreated();
if (_mainWindow is null) throw new InvalidOperationException("Window creation returned null.");

When it happens

Trigger: InitializeFrame invoked before EnsureWindowCreated / ActivateMainWindow has set _mainWindow — e.g. navigating during OnLaunched before the window was created, or a code path that calls InitializeFrame directly.

Common situations: Custom startup calling InitializeFrame early; window creation guarded by a condition that evaluated false; refactor that reordered EnsureWindowCreated after InitializeFrame; headless test harness that skips window creation.

Related errors

• The Window should be created later in the application lifecy
• Failed to load Page {e.SourcePageType}: {e.Exception}
• Failed to load {e.SourcePageType.FullName}: {e.Exception}
• Failed to load {e.SourcePageType.FullName}: {e.Exception}
• Failed to load {e.SourcePageType.FullName}: {e.Exception}

AI-assisted analysis of unoplatform/uno@0418340488 (2026-08-13). Data as JSON: /api/errors/880adc7d291f4655. Report an issue: GitHub.