dotnet/maui · error · InvalidOperationException

InsertPageBefore is not supported globally on Android, pleas

Error message

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

What it means

Thrown by the Platform class's explicit INavigation.InsertPageBefore implementation. On Android, the application-level (global) navigation only supports modal push/pop; page-stack operations (InsertPageBefore, PushAsync, PopAsync, PopToRootAsync, RemovePage) require a NavigationPage host. The platform's INavigation deliberately throws to direct developers to use NavigationPage for stack-based navigation.

Source

Thrown at src/Compatibility/Core/src/Android/AppCompat/Platform.cs:115

		{
			if (_disposed)
				return;
			_disposed = true;

			FormsAppCompatActivity.BackPressed -= HandleBackPressed;

			SetPage(null);

			var activity = _context?.GetActivity();
			if (_embedded && activity != null)
			{
				PopupManager.Unsubscribe(activity);
			}
		}

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

		IReadOnlyList<Page> INavigation.ModalStack => _navModel.Modals.ToList();

		IReadOnlyList<Page> INavigation.NavigationStack => new List<Page>();

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

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

		Task<Page> INavigation.PopModalAsync()
		{

View on GitHub (pinned to f377ff1c5e)

Solutions

Wrap your root page in a NavigationPage (new NavigationPage(rootPage)) so that page-stack navigation resolves to the NavigationPage's INavigation, not the platform's.
Use only PushModalAsync/PopModalAsync at the global/platform level on Android.
Refactor shared navigation code to obtain the Navigation instance from a NavigationPage, not from Application.Current.MainPage.Navigation.

Example fix

// before
Application.Current.MainPage = new ContentPage();
await Application.Current.MainPage.Navigation.PushAsync(new DetailPage()); // throws on Android

// after
Application.Current.MainPage = new NavigationPage(new ContentPage());
await Application.Current.MainPage.Navigation.PushAsync(new DetailPage());

Defensive patterns

Strategy: validation

Validate before calling

// Ensure a NavigationPage hosts the root before using InsertPageBefore.
static bool SupportsGlobalStackNavigation(Page root) => root is NavigationPage;
// Usage:
if (!SupportsGlobalStackNavigation(Application.Current.MainPage))
    Application.Current.MainPage = new NavigationPage(Application.Current.MainPage);

Prevention

Standardize on NavigationPage as the root for any app using page-stack navigation on Android.
Create a shared INavigationService that throws or redirects to modals when no NavigationPage is present.
Write platform-aware unit tests that assert page-stack operations are only invoked under a NavigationPage.

When it happens

Trigger: Calling Application.Current.MainPage.Navigation.InsertPageBefore(...) (or any page-stack INavigation method obtained from the application/platform level rather than from a NavigationPage) on Android. The global Navigation property resolves to this Platform implementation when the MainPage is not wrapped in a NavigationPage.

Common situations: Cross-platform code that uses the page's Navigation property without ensuring a NavigationPage is the root. iOS works because its platform navigation supports these calls; Android does not. Porting an iOS-first app to Android.

Related errors

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