dotnet/maui · error · InvalidOperationException

InsertPageBefore is not supported globally on macOS, please

Error message

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

What it means

InsertPageBefore inserts a page before another in the navigation stack; the macOS global Platform has no page stack, so PlatformNavigation throws InvalidOperationException. Insertion requires a NavigationPage whose renderer owns the stack. This is the last of the global-stack-op limitations on macOS.

Source

Thrown at src/Compatibility/Core/src/MacOS/PlatformNavigation.cs:90

		Task INavigation.PushModalAsync(Page modal, bool animated)
		{
			return _modalTracker.PushAsync(modal, _animateModals && animated);
		}

		Task<Page> INavigation.PopModalAsync(bool animated)
		{
			return _modalTracker.PopAsync(animated);
		}

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

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

		protected virtual void Dispose(bool disposing)
		{
			if (!_disposed)
			{
				if (disposing)
				{
					_modalTracker.Dispose();
					_modalTracker = null;
					_platformRenderer = null;
				}

				_disposed = true;
			}
		}

View on GitHub (pinned to f377ff1c5e)

Solutions

Ensure the page is inside a NavigationPage (MainPage = new NavigationPage(root)) and call InsertPageBefore on a page within it.
Re-implement the flow using modal push/pop if a NavigationPage is not appropriate.
Guard the call so InsertPageBefore only runs when a NavigationPage ancestor exists on macOS.

Example fix

// before
MainPage = new ContentPage();
Navigation.InsertPageBefore(newPage, current); // throws on macOS

// after
MainPage = new NavigationPage(new ContentPage());
Navigation.InsertPageBefore(newPage, current);

Defensive patterns

Strategy: validation

Validate before calling

if (Navigation.NavigationStack.Contains(before))
    Navigation.InsertPageBefore(page, before);

Type guard

static bool IsOnStack(Page p) => Navigation.NavigationStack.Contains(p);

Prevention

Ensure a NavigationPage hosts the stack before inserting.
Verify the anchor page is still present.
Serialize stack mutations to prevent desync.

When it happens

Trigger: Calling Navigation.InsertPageBefore(page, before) when Navigation resolves to the global macOS Platform — MainPage is not a NavigationPage, so there is no stack to insert into.

Common situations: Navigation reshaping code (e.g. inserting a page before the current one) shared across platforms. Custom routers/Shell interactions hitting the global Platform on macOS. Logout/reset flows that rebuild the stack.

Related errors

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