dotnet/maui · error · InvalidOperationException

PopToRoot is not supported globally on Windows, please use a

Error message

PopToRoot is not supported globally on Windows, please use a LightNavigationPage.

What it means

IFormsNavigation.PopToRoot throws InvalidOperationException stating PopToRoot is not supported globally on Windows and instructs to use a LightNavigationPage. The window-level navigation proxy rejects full-stack pops; only a LightNavigationPage implements them.

Source

Thrown at src/Compatibility/Core/src/WPF/Interfaces/IFormsNavigation.cs:80

		public void PopModal()
		{
			PopModal(true);
		}

		public void PopModal(bool animated)
		{
			ParentWindow?.PopModal(animated);
		}

		public void PopToRoot()
		{
			PopToRoot(true);
		}

		public void PopToRoot(bool animated)
		{
			throw new InvalidOperationException(
				"PopToRoot is not supported globally on Windows, please use a LightNavigationPage.");
		}

		public void Push(object page)
		{
			Push(page, true);
		}

		public void Push(object page, bool animated)
		{
			throw new InvalidOperationException("Push is not supported globally on Windows, please use a LightNavigationPage.");
		}

		public void PushModal(object page)
		{
			PushModal(page, true);
		}

View on GitHub (pinned to f377ff1c5e)

Solutions

Use a LightNavigationPage and call PopToRoot on that instance.
Branch by platform: only call PopToRootAsync when Navigation is a per-page NavigationPage.
Verify the Forms NavigationProxy resolves to the page-level NavigationPage.
Provide a WPF-specific INavigation wrapper that throws a clearer message or delegates correctly.

Example fix

// before
await Navigation.PopToRootAsync();

// after
if (Navigation is LightNavigationPage lnp)
    await lnp.PopToRootAsync();

Defensive patterns

Strategy: type-guard

Validate before calling

if (Navigation is LightNavigationPage lnp) await lnp.PopToRootAsync();
else throw new PlatformNotSupportedException("Use LightNavigationPage on WPF.");

Type guard

static bool CanPopToRoot(NavigationProxy n) => n is LightNavigationPage;

Try / catch

try { await Navigation.PopToRootAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("LightNavigationPage"))
{ /* ensure LightNavigationPage, retry */ }

Prevention

Wrap pages in LightNavigationPage before any pop-to-root on WPF.
Branch by platform for stack-reset calls.
Verify NavigationProxy is per-page.

When it happens

Trigger: Calling Navigation.PopToRootAsync() against the FormsWindow-level navigation proxy; porting code that uses a global navigation stack.

Common situations: Cross-platform navigation code calling PopToRootAsync unconditionally; not wrapping pages in a LightNavigationPage; misrouted NavigationProxy.

Related errors

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