dotnet/maui · error · InvalidOperationException

PopToRootAsync is not supported globally on iOS, please use

Error message

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

What it means

Platform.cs throws InvalidOperationException for INavigation.PopToRootAsync. Same iOS restriction: global PopToRoot requires a NavigationPage-managed stack, since the global Platform only tracks modals.

Source

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

			else
				await _renderer.DismissViewControllerAsync(animated);

			modal.DisposeModalAndChildRenderers();

			if (!IsModalPresentedFullScreen(modal))
				Page.GetCurrentPage()?.SendAppearing();

			return modal;
		}

		Task INavigation.PopToRootAsync()
		{
			return ((INavigation)this).PopToRootAsync(true);
		}

		Task INavigation.PopToRootAsync(bool animated)
		{
			throw new InvalidOperationException("PopToRootAsync is not supported globally on iOS, please use a NavigationPage.");
		}

		Task INavigation.PushAsync(Page root)
		{
			return ((INavigation)this).PushAsync(root, true);
		}

		Task INavigation.PushAsync(Page root, bool animated)
		{
			throw new InvalidOperationException("PushAsync is not supported globally on iOS, please use a NavigationPage.");
		}

		Task INavigation.PushModalAsync(Page modal)
		{
			return ((INavigation)this).PushModalAsync(modal, true);
		}

		Task INavigation.PushModalAsync(Page modal, bool animated)

View on GitHub (pinned to f377ff1c5e)

Solutions

Ensure the root is a NavigationPage and call PopToRootAsync on its Navigation property.
If using Shell, use Shell navigation APIs instead.
If using modals only, dismiss modals manually with PopModalAsync.

Example fix

// before
await Application.Current.MainPage.Navigation.PopToRootAsync();
// after
// wrap root: new NavigationPage(root)
await Application.Current.MainPage.Navigation.PopToRootAsync();

Defensive patterns

Strategy: validation

Validate before calling

if (!(Application.Current.MainPage is NavigationPage))
    Application.Current.MainPage = new NavigationPage(Application.Current.MainPage);
await Application.Current.MainPage.Navigation.PopToRootAsync();

Type guard

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

Prevention

Use NavigationPage for PopToRootAsync on iOS.
Switch to Shell navigation if using Shell.
Dismiss modals with PopModalAsync when not using a navigation stack.

When it happens

Trigger: Calling MainPage.Navigation.PopToRootAsync() when MainPage is not a NavigationPage.

Common situations: Shared navigation code targeting the global Navigation interface on iOS; replacing NavigationPage with a TabbedPage or Shell and still calling PopToRootAsync.

Related errors

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