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

The Windows Platform class's explicit INavigation.InsertPageBefore throws unconditionally. Inserting a page before another in the navigation stack is only supported through a NavigationPage host on Windows, not the global Platform navigation context.

Source

Thrown at src/Compatibility/Core/src/Windows/Platform.cs:233

		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));

View on GitHub (pinned to f377ff1c5e)

Solutions

Use NavigationPage as root so InsertPageBefore operates on its managed stack
Rebuild the navigation stack from scratch rather than inserting mid-stack
Abstract navigation behind a service with platform-specific implementations

Example fix

// before
MainPage = new MyContentPage();
Navigation.InsertPageBefore(newRoot, MainPage); // throws

// after
MainPage = new NavigationPage(new MyContentPage());
Navigation.InsertPageBefore(newRoot, currentRoot); // works

Defensive patterns

Strategy: validation

Validate before calling

// Before calling InsertPageBefore, verify NavigationPage
if (Application.Current.MainPage is NavigationPage navPage)
{
    navPage.Navigation.InsertPageBefore(newPage, existingPage);
}
else
{
    // Windows: rebuild navigation from scratch
    Application.Current.MainPage = new NavigationPage(newPage);
}

Type guard

static bool SupportsInsertPage()
{
    return Application.Current.MainPage is NavigationPage;
}

Prevention

Ensure NavigationPage hosts the root before using InsertPageBefore
Consider rebuilding the stack rather than inserting mid-stack on Windows
Test dynamic navigation hierarchy construction on all platforms

When it happens

Trigger: Calling Application.Current.MainPage.Navigation.InsertPageBefore(newPage, existingPage) when MainPage is not a NavigationPage. Common in dynamic navigation flows where pages are inserted at specific positions.

Common situations: Building dynamic navigation hierarchies; inserting a page before the current root for back-navigation purposes; shared cross-platform code.

Related errors

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