dotnet/maui · error · InvalidOperationException

InsertPageBefore is not supported globally on Windows, pleas

Error message

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

What it means

IFormsNavigation.InsertPageBefore throws InvalidOperationException stating InsertPageBefore is not supported globally on Windows and instructs to use a LightNavigationPage. The global FormsWindow navigation surface deliberately rejects page-stack mutations; only a LightNavigationPage instance supports InsertPageBefore semantics on WPF.

Source

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

		void RemovePage(object page);
	}

	public class DefaultNavigation : IFormsNavigation
	{
		public FormsWindow ParentWindow
		{
			get
			{
				if (System.Windows.Application.Current.MainWindow is FormsWindow)
					return System.Windows.Application.Current.MainWindow as FormsWindow;
				return null;
			}
		}

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

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

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

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

View on GitHub (pinned to f377ff1c5e)

Solutions

Wrap the target page hierarchy in a LightNavigationPage and call InsertPageBefore on that instance instead of the global proxy.
Replace Navigation.InsertPageBefore usages with LightNavigationPage.InsertPageBefore in WPF-specific code paths.
Detect the platform and branch to the LightNavigationPage path for Windows.
Audit NavigationProxy usage to ensure INavigation resolves to a per-page NavigationPage.

Example fix

// before
Navigation.InsertPageBefore(newPage, current);

// after
if (Navigation is LightNavigationPage lnp)
    lnp.InsertPageBefore(newPage, current);
else
    throw new PlatformNotSupportedException("Use LightNavigationPage on WPF.");

Defensive patterns

Strategy: type-guard

Validate before calling

if (Navigation is LightNavigationPage lnp) lnp.InsertPageBefore(page, before);
else throw new PlatformNotSupportedException("Use LightNavigationPage on WPF.");

Type guard

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

Try / catch

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

Prevention

Wrap pages in a LightNavigationPage at construction on WPF.
Branch navigation by platform or by Navigation type.
Provide a WPF-specific INavigation implementation.

When it happens

Trigger: Calling Navigation.InsertPageBefore on the global/window-level navigation proxy returned by the WPF host; mixing global and per-page navigation; routing InsertPageBefore to FormsWindow.ParentWindow instead of a NavigationPage.

Common situations: Porting code that uses a single global Navigation to WPF; assuming window-level nav supports the full INavigation contract; not wrapping pages in a LightNavigationPage.

Related errors

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