dotnet/maui · error · InvalidOperationException

InsertPageBefore is not supported globally on iOS, please us

Error message

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

What it means

Platform.cs (the global Platform, not NavigationPage) explicitly throws InvalidOperationException for INavigation.InsertPageBefore because global navigation is not supported on iOS — navigation stack management requires a NavigationPage. The global INavigation is a limited shim that only supports modal push/pop.

Source

Thrown at src/Compatibility/Core/src/iOS/Platform.cs:90

		protected virtual void Dispose(bool disposing)
		{
			if (_disposed)
			{
				return;
			}

			_disposed = true;

			if (disposing)
			{
				_renderer.Dispose();
			}
		}

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

		IReadOnlyList<Page> INavigation.ModalStack
		{
			get
			{
				if (_disposed)
					return new List<Page>();

				return _modals;
			}
		}

		IReadOnlyList<Page> INavigation.NavigationStack
		{
			get { return new List<Page>(); }
		}

View on GitHub (pinned to f377ff1c5e)

Solutions

Wrap the page in a NavigationPage: new NavigationPage(rootPage).
Use the NavigationPage's Navigation property for stack operations.
Refactor shared navigation code to target NavigationPage on iOS.

Example fix

// before
Application.Current.MainPage.Navigation.InsertPageBefore(page, current);
// after
var nav = new NavigationPage(rootPage);
// (set as MainPage, then call) nav.Navigation.InsertPageBefore(page, current);

Defensive patterns

Strategy: validation

Validate before calling

// Ensure root is NavigationPage before stack operations:
if (!(Application.Current.MainPage is NavigationPage))
    Application.Current.MainPage = new NavigationPage(Application.Current.MainPage);

Type guard

static bool SupportsStackNavigation(Page p) => p is NavigationPage;

Prevention

Wrap root in NavigationPage for stack operations on iOS.
Use NavigationPage.Navigation for InsertPageBefore/RemovePage.
Detect iOS in shared code and avoid global navigation stack calls.

When it happens

Trigger: Calling Navigation.InsertPageBefore on the Application.MainPage.Navigation when MainPage is not a NavigationPage; reaching the Platform-level INavigation via the global accessor.

Common situations: Code that assumes MainPage.Navigation supports stack operations on all platforms; navigating without wrapping the root page in a NavigationPage; shared code that worked on Android (which has a global navigation host) but fails on iOS.

Related errors

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