dotnet/maui · error · InvalidOperationException

InsertPageBefore is not supported globally on Windows…

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.

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.

Appendix: 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)