dotnet/maui · error · InvalidOperationException

InsertPageBefore is not supported globally on Windows, pleas

Error message

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

What it means

Thrown by the WPF Platform's INavigation.InsertPageBefore implementation. Inserting a page before another in the navigation stack is unsupported at the global platform level on Windows/WPF. This operation requires a NavigationPage to manage the ordered page list.

Source

Thrown at src/Compatibility/Core/src/WPF/Platform.cs:218

		Task<Page> INavigation.PopAsync(bool animated)
		{
			throw new InvalidOperationException("PopAsync is not supported globally on Windows, please use a NavigationPage.");
		}

		Task INavigation.PopToRootAsync(bool animated)
		{
			throw new InvalidOperationException("PopToRootAsync is not supported globally on Windows, please use a NavigationPage.");
		}

		void INavigation.RemovePage(Page page)
		{
			throw new InvalidOperationException("RemovePage is not supported globally on Windows, please use a NavigationPage.");
		}

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

		Task INavigation.PushModalAsync(Page page)
		{
			return ((INavigation)this).PushModalAsync(page, true);
		}

		Task<Page> INavigation.PopModalAsync()
		{
			return ((INavigation)this).PopModalAsync(true);
		}

		Task INavigation.PushModalAsync(Page page, bool animated)
		{
			if (page == null)
				throw new ArgumentNullException(nameof(page));

			var tcs = new TaskCompletionSource<bool>();

View on GitHub (pinned to f377ff1c5e)

Solutions

Wrap the root page in a NavigationPage so InsertPageBefore has a stack to operate on.
Call InsertPageBefore on a NavigationPage reference directly.
If only reordering the root, set MainPage to the desired page directly.

Example fix

// before
Application.Current.MainPage.Navigation.InsertPageBefore(new Step1Page(), existingPage);

// after
Application.Current.MainPage = new NavigationPage(new RootPage());
Application.Current.MainPage.Navigation.InsertPageBefore(new Step1Page(), existingPage);

Defensive patterns

Strategy: validation

Validate before calling

if (Application.Current.MainPage is NavigationPage navPage)
    navPage.Navigation.InsertPageBefore(page, before);

Type guard

static bool CanInsertPage(Page root) => root is NavigationPage;

Prevention

Ensure a NavigationPage host exists before InsertPageBefore.
Validate the page type in shared navigation code.

When it happens

Trigger: Calling Application.Current.MainPage.Navigation.InsertPageBefore(page, before) when MainPage is not a NavigationPage.

Common situations: Shared code inserts a page before an existing one (e.g., inserting a wizard step), but the WPF root was not set up as a NavigationPage.

Related errors

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