dotnet/maui · error · InvalidOperationException

PopAsync is not supported globally on iOS, please use a Navi

Error message

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

What it means

Platform.cs throws InvalidOperationException for INavigation.PopAsync, mirroring iOS's restriction that global (non-NavigationPage) navigation stacks are unsupported. On iOS, the global INavigation only handles modal push/pop; PopAsync must go through a NavigationPage.

Source

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

					return new List<Page>();

				return _modals;
			}
		}

		IReadOnlyList<Page> INavigation.NavigationStack
		{
			get { return new List<Page>(); }
		}

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

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

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

		async Task<Page> INavigation.PopModalAsync(bool animated)
		{
			var modal = _modals.Last();
			_modals.Remove(modal);
			modal.DescendantRemoved -= HandleChildRemoved;

			var controller = GetRenderer(modal) as UIViewController;

			if (_modals.Count >= 1 && controller != null)
				await controller.DismissViewControllerAsync(animated);
			else

View on GitHub (pinned to f377ff1c5e)

Solutions

Use NavigationPage as the root and call PopAsync on its Navigation property.
For modal flows, use PopModalAsync instead.
Ensure the page from which PopAsync is called is hosted inside a NavigationPage.

Example fix

// before
await Application.Current.MainPage.Navigation.PopAsync();
// after
// MainPage should be a NavigationPage
await Application.Current.MainPage.Navigation.PopAsync(); // after wrapping root in NavigationPage

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

Type guard

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

Prevention

Host pages in NavigationPage for PushAsync/PopAsync on iOS.
Use PopModalAsync for modals.
Refactor shared navigation to be NavigationPage-rooted.

When it happens

Trigger: Calling MainPage.Navigation.PopAsync() when MainPage is not a NavigationPage; shared code assuming global navigation stack semantics.

Common situations: Cross-platform navigation code that works on Android but is invoked on iOS without a NavigationPage root; setting MainPage to a ContentPage then calling Navigation.PopAsync.

Related errors

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