dotnet/maui · error · InvalidOperationException

InsertPageBefore is not supported globally on GTK, please us

Error message

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

What it means

The GTK Platform's explicit INavigation implementation deliberately does NOT support InsertPageBefore at the global (application) navigation level. Calling it throws InvalidOperationException directing the developer to use a NavigationPage instead, because GTK global navigation has no page-stack to insert into.

Source

Thrown at src/Compatibility/Core/src/GTK/Platform.cs:152

			if (viewRenderer == null)
			{
				viewRenderer = CreateRenderer(mainPage);
				SetRenderer(mainPage, viewRenderer);

				PlatformRenderer.Add(viewRenderer.Container);
				PlatformRenderer.ShowAll();
			}
		}

		private void HandleChildRemoved(object sender, ElementEventArgs e)
		{
			var view = e.Element;
			DisposeModelAndChildrenRenderers(view);
		}

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

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

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

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

		Task<Page> INavigation.PopModalAsync(bool animated)

View on GitHub (pinned to f377ff1c5e)

Solutions

Wrap the page hierarchy in a NavigationPage and call InsertPageBefore on the NavigationPage's navigation (NavigationPage.Navigation.InsertPageBefore).
Restructure so all stack-manipulating navigation goes through a NavigationPage on GTK.
Guard platform-specific navigation calls behind a runtime/platform check.

Example fix

// before — global insert (throws on GTK)
Application.Current.MainPage.Navigation.InsertPageBefore(newPage, currentPage);
// after — use a NavigationPage
var nav = new NavigationPage(rootPage);
Application.Current.MainPage = nav;
nav.Navigation.InsertPageBefore(newPage, currentPage);

Defensive patterns

Strategy: validation

Validate before calling

static void SafeInsertBefore(Page page, Page before)
{
    var nav = Application.Current?.MainPage as NavigationPage
        ?? throw new InvalidOperationException("Use a NavigationPage root to insert pages on GTK.");
    nav.Navigation.InsertPageBefore(page, before);
}

Type guard

static bool HasNavigationPageRoot => Application.Current?.MainPage is NavigationPage;

Prevention

Root the GTK app in a NavigationPage to enable stack operations.
Branch navigation code per platform or guard on NavigationPage root.
Avoid calling global INavigation stack ops on GTK.

When it happens

Trigger: Invoking INavigation.InsertPageBefore on the application-level navigation (obtained without a NavigationPage), i.e. trying to manipulate the global page stack on GTK.

Common situations: Code written for a platform that supports global InsertPageBefore (e.g. the default Xamarin.Forms navigation) being run on GTK without a NavigationPage root; shared navigation helpers that assume global stack operations.

Related errors

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