dotnet/maui · error · InvalidOperationException

PushAsync is not supported globally on Windows, please use a

Error message

PushAsync is not supported globally on Windows, please use a NavigationPage.

What it means

Thrown by the WPF Platform's explicit INavigation.PushAsync(Page, bool) implementation. The global Windows/WPF platform cannot push pages onto a stack because it has no built-in navigation host. Page-stack navigation requires a NavigationPage wrapper.

Source

Thrown at src/Compatibility/Core/src/WPF/Platform.cs:198

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

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

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

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

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

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

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

		void INavigation.InsertPageBefore(Page page, Page before)

View on GitHub (pinned to f377ff1c5e)

Solutions

Set Application.Current.MainPage to a new NavigationPage(rootPage) before calling PushAsync.
Use NavigationPage.PushAsync from a NavigationPage instance rather than the global proxy.
Conditional-check in shared code: if (mainPage is NavigationPage navPage) navPage.PushAsync(page).

Example fix

// before
Application.Current.MainPage = new MainPage();
await Application.Current.MainPage.Navigation.PushAsync(new DetailPage());

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

Defensive patterns

Strategy: validation

Validate before calling

if (Application.Current.MainPage is NavigationPage navPage)
    await navPage.PushAsync(page);

Type guard

static bool CanPush(Page root) => root is NavigationPage;

Prevention

Bootstrap the WPF/Windows app with new NavigationPage(rootPage) as MainPage.
In shared code, check for NavigationPage before calling PushAsync on the global proxy.

When it happens

Trigger: Calling Application.Current.MainPage.Navigation.PushAsync(page) or the equivalent global INavigation.PushAsync when MainPage is not a NavigationPage.

Common situations: Shared PCL/netstandard code calls Navigation.PushAsync at startup, but the WPF host was initialized with a bare ContentPage. Common when porting from iOS/Android where MainPage was already a NavigationPage.

Related errors

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