{"record":{"id":"8e9485392d79faf8","repo":"dotnet/maui","slug":"popasync-is-not-supported-globally-on-macos-pleas","errorCode":null,"errorMessage":"PopAsync is not supported globally on macOS, please use a NavigationPage.","messagePattern":"PopAsync is not supported globally on macOS, please use a NavigationPage\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Compatibility/Core/src/MacOS/PlatformNavigation.cs","lineNumber":40,"sourceCode":"\n\t\tpublic IReadOnlyList<Page> ModalStack => _modalTracker.ModalStack;\n\n\t\tpublic IReadOnlyList<Page> NavigationStack => new List<Page>();\n\n\t\tpublic bool AnimateModalPages\n\t\t{\n\t\t\tget { return _animateModals; }\n\t\t\tset { _animateModals = value; }\n\t\t}\n\n\t\tTask<Page> INavigation.PopAsync()\n\t\t{\n\t\t\treturn ((INavigation)this).PopAsync(true);\n\t\t}\n\n\t\tTask<Page> INavigation.PopAsync(bool animated)\n\t\t{\n\t\t\tthrow new InvalidOperationException(\"PopAsync is not supported globally on macOS, please use a NavigationPage.\");\n\t\t}\n\n\t\tTask INavigation.PopToRootAsync()\n\t\t{\n\t\t\treturn ((INavigation)this).PopToRootAsync(true);\n\t\t}\n\n\t\tTask INavigation.PopToRootAsync(bool animated)\n\t\t{\n\t\t\tthrow new InvalidOperationException(\"PopToRootAsync is not supported globally on macOS, please use a NavigationPage.\");\n\t\t}\n\n\t\tTask INavigation.PushAsync(Page root)\n\t\t{\n\t\t\treturn ((INavigation)this).PushAsync(root, true);\n\t\t}\n\n\t\tTask INavigation.PushAsync(Page root, bool animated)","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/dotnet/maui/blob/f377ff1c5ee04d334d8a925f50c83a6b7afddf03/src/Compatibility/Core/src/MacOS/PlatformNavigation.cs#L22-L58","documentation":"The macOS global Platform (PlatformNavigation) implements INavigation but exposes only modal push/pop; the non-modal PopAsync is a stack operation it does not support, so it throws InvalidOperationException. Non-modal navigation on macOS must go through a NavigationPage whose renderer owns the stack. This is the macOS analogue of the GTK global-stack limitation.","triggerScenarios":"Calling await Navigation.PopAsync() where Navigation resolves to the global macOS Platform — i.e. the Page's parent is the Application/Platform root, not a NavigationPage (MainPage is a bare page).","commonSituations":"Shared navigation code that assumes global Pop works on all backends. App with MainPage set to a ContentPage on macOS. Hardware/menu back handling calling PopAsync unconditionally.","solutions":["Host the page in a NavigationPage: MainPage = new NavigationPage(root); then call PopAsync on a page within it.","If using modals, call Navigation.PopModalAsync() instead, which the global Platform supports.","Runtime-guard PopAsync so it only runs when a NavigationPage ancestor exists."],"exampleFix":"// before\nMainPage = new ContentPage();\nawait page.Navigation.PopAsync(); // throws on macOS\n\n// after\nMainPage = new NavigationPage(new ContentPage());\nawait page.Navigation.PopAsync();","handlingStrategy":"validation","validationCode":"if (Application.Current.MainPage is NavigationPage)\n    await page.Navigation.PopAsync();\nelse if (Navigation.ModalStack.Count > 0)\n    await Navigation.PopModalAsync();","typeGuard":"static bool HasNavStack() => Application.Current?.MainPage is NavigationPage;","tryCatchPattern":null,"preventionTips":["Use a NavigationPage when non-modal back navigation is needed on macOS.","Treat the global Navigation as modal-only on macOS.","Guard back/menu handlers against empty stacks."],"tags":["macos","navigation","navigationpage","platform-limitation","maui","xamarin"],"backgroundTag":null,"analyzedSha":"f377ff1c5ee04d334d8a925f50c83a6b7afddf03","analyzedAt":"2026-08-13T14:26:18.069Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}