dotnet/maui · error · InvalidOperationException

PushAsync is not supported globally on iOS, please use a Nav

Error message

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

What it means

Platform.cs throws InvalidOperationException for INavigation.PushAsync on iOS. The global Platform only supports modal presentation; pushing a page onto a navigation stack requires a NavigationPage.

Source

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

		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)
		{
			EndEditing();

			var elementConfiguration = modal as IElementConfiguration<Page>;

			var presentationStyle = elementConfiguration?.On<PlatformConfiguration.iOS>()?.ModalPresentationStyle().ToPlatformModalPresentationStyle();

			bool shouldFire = true;

			if (Forms.IsiOS13OrNewer)

View on GitHub (pinned to f377ff1c5e)

Solutions

Wrap the root in a NavigationPage and call PushAsync on that.
Use PushModalAsync for modal presentation.
Refactor shared navigation to be NavigationPage-rooted on iOS.

Example fix

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

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.PushAsync(page);

Type guard

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

Prevention

Wrap root in NavigationPage for PushAsync on iOS.
Use PushModalAsync for modal presentation.
Keep shared navigation NavigationPage-rooted.

When it happens

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

Common situations: Cross-platform code that works on Android but is invoked on iOS with a non-NavigationPage root; misusing Navigation.PushAsync from a ContentPage that is not inside a NavigationPage.

Related errors

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