{"record":{"id":"32ba5ae370b6aa08","repo":"dotnet/maui","slug":"poptorootasync-is-not-supported-globally-on-macos","errorCode":null,"errorMessage":"PopToRootAsync is not supported globally on macOS, please use a NavigationPage.","messagePattern":"PopToRootAsync 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":50,"sourceCode":"\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)\n\t\t{\n\t\t\tthrow new InvalidOperationException(\"PushAsync is not supported globally on macOS, please use a NavigationPage.\");\n\t\t}\n\n\t\tTask INavigation.PushModalAsync(Page modal)\n\t\t{\n\t\t\treturn ((INavigation)this).PushModalAsync(modal, true);\n\t\t}\n\n\t\tTask<Page> INavigation.PopModalAsync()","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/dotnet/maui/blob/f377ff1c5ee04d334d8a925f50c83a6b7afddf03/src/Compatibility/Core/src/MacOS/PlatformNavigation.cs#L32-L68","documentation":"The macOS global Platform does not maintain a page navigation stack; PopToRootAsync is a stack operation with no stack to operate on, so PlatformNavigation throws InvalidOperationException. Root-to-root popping must be performed by a NavigationPage that owns the stack. Same family as the global Pop/Push/RemovePage/InsertPageBefore limitations on macOS.","triggerScenarios":"Calling await Navigation.PopToRootAsync() when Navigation points at the global macOS Platform — MainPage is not a NavigationPage, so no stack exists.","commonSituations":"Shared code calling PopToRootAsync across all backends. App with a bare root ContentPage on macOS. Reset-flow code (e.g. logout returning to root) assuming global stack support.","solutions":["Wrap the root in a NavigationPage and PopToRootAsync through it: MainPage = new NavigationPage(root); then await page.Navigation.PopToRootAsync();","If only modals are used, switch to Navigation.PopModalAsync() (may need a loop to clear the modal stack).","Guard the call to only run when NavigationPage is in the hierarchy on macOS."],"exampleFix":"// before\nMainPage = new ContentPage();\nawait page.Navigation.PopToRootAsync(); // throws on macOS\n\n// after\nMainPage = new NavigationPage(new ContentPage());\nawait page.Navigation.PopToRootAsync();","handlingStrategy":"validation","validationCode":"if (page.Parent is NavigationPage)\n    await page.Navigation.PopToRootAsync();","typeGuard":"static bool IsNavigationPageRoot(Page root) => root is NavigationPage;","tryCatchPattern":null,"preventionTips":["Wrap the root in a NavigationPage for stack-level navigation.","Guard reset/logout flows to only PopToRoot when a stack exists.","Keep platform navigation capabilities documented."],"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"}