dotnet/maui · error · InvalidOperationException

Push is not supported globally on Windows, please use a Ligh

Error message

Push is not supported globally on Windows, please use a LightNavigationPage.

What it means

IFormsNavigation.Push (and Push(bool)) throw InvalidOperationException stating Push is not supported globally on Windows and instructs to use a LightNavigationPage. The FormsWindow-level navigation proxy rejects stack pushes; only a LightNavigationPage implements them. (PushModal is supported at the window level and delegates to ParentWindow.)

Source

Thrown at src/Compatibility/Core/src/WPF/Interfaces/IFormsNavigation.cs:91

		public void PopToRoot()
		{
			PopToRoot(true);
		}

		public void PopToRoot(bool animated)
		{
			throw new InvalidOperationException(
				"PopToRoot is not supported globally on Windows, please use a LightNavigationPage.");
		}

		public void Push(object page)
		{
			Push(page, true);
		}

		public void Push(object page, bool animated)
		{
			throw new InvalidOperationException("Push is not supported globally on Windows, please use a LightNavigationPage.");
		}

		public void PushModal(object page)
		{
			PushModal(page, true);
		}

		public void PushModal(object page, bool animated)
		{
			ParentWindow?.PushModal(page, animated);
		}

		public void RemovePage(object page)
		{
			throw new InvalidOperationException(
				"RemovePage is not supported globally on Windows, please use a LightNavigationPage.");
		}

View on GitHub (pinned to f377ff1c5e)

Solutions

Wrap pages in a LightNavigationPage and push via that instance.
Branch shared code by platform: use LightNavigationPage on WPF.
Verify the navigation proxy resolves to a page-level NavigationPage, not the window.
Use PushModalAsync for window-level modal pushes if that matches intent.

Example fix

// before
await Navigation.PushAsync(new ContentPage());

// after
if (Navigation is LightNavigationPage lnp)
    await lnp.PushAsync(new ContentPage());

Defensive patterns

Strategy: type-guard

Validate before calling

if (Navigation is LightNavigationPage lnp) await lnp.PushAsync(page);
else throw new PlatformNotSupportedException("Use LightNavigationPage on WPF.");

Type guard

static bool CanPush(NavigationProxy n) => n is LightNavigationPage;

Try / catch

try { await Navigation.PushAsync(page); }
catch (InvalidOperationException ex) when (ex.Message.Contains("LightNavigationPage"))
{ /* wrap in LightNavigationPage, retry */ }

Prevention

Wrap pages in LightNavigationPage for stack pushes on WPF.
Use PushModalAsync for window-level modal pushes if appropriate.
Branch shared navigation by platform.

When it happens

Trigger: Calling Navigation.PushAsync(page) against the FormsWindow navigation proxy; pushing pages without a LightNavigationPage container; shared code that pushes via the global proxy.

Common situations: Cross-platform navigation pushing pages directly; embedding pages without a NavigationPage wrapper on WPF.

Related errors

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