{"record":{"id":"8312de5f968eaf10","repo":"dotnet/maui","slug":"pushasync-is-not-supported-globally-on-macos-plea","errorCode":null,"errorMessage":"PushAsync is not supported globally on macOS, please use a NavigationPage.","messagePattern":"PushAsync 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":60,"sourceCode":"\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()\n\t\t{\n\t\t\treturn ((INavigation)this).PopModalAsync(true);\n\t\t}\n\n\t\tTask INavigation.PushModalAsync(Page modal, bool animated)\n\t\t{\n\t\t\treturn _modalTracker.PushAsync(modal, _animateModals && animated);\n\t\t}\n\n\t\tTask<Page> INavigation.PopModalAsync(bool animated)","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/dotnet/maui/blob/f377ff1c5ee04d334d8a925f50c83a6b7afddf03/src/Compatibility/Core/src/MacOS/PlatformNavigation.cs#L42-L78","documentation":"The macOS global Platform has no non-modal page stack, so PushAsync has nowhere to push and PlatformNavigation throws InvalidOperationException. Pushing a page requires a NavigationPage whose renderer manages the stack. The global Platform only supports modal push/pop via its ModalPageTracker.","triggerScenarios":"Calling await Navigation.PushAsync(page) where Navigation resolves to the global macOS Platform: the calling Page's parent is the Application root (MainPage is not a NavigationPage).","commonSituations":"Shared code that calls Navigation.PushAsync on every platform. App structured with a single root ContentPage on macOS. Migrating navigation logic from iOS/Android.","solutions":["Use a NavigationPage as MainPage: MainPage = new NavigationPage(root); then await page.Navigation.PushAsync(next).","If the intent is modal, use await Navigation.PushModalAsync(page) which the global Platform supports.","Gate PushAsync on macOS behind a check that a NavigationPage ancestor exists."],"exampleFix":"// before\nMainPage = new ContentPage();\nawait page.Navigation.PushAsync(detail); // throws on macOS\n\n// after\nMainPage = new NavigationPage(new ContentPage());\nawait page.Navigation.PushAsync(detail);","handlingStrategy":"validation","validationCode":"if (Application.Current.MainPage is NavigationPage)\n    await page.Navigation.PushAsync(next);\nelse\n    await page.Navigation.PushModalAsync(next);","typeGuard":"static bool HasNavStack() => Application.Current?.MainPage is NavigationPage;","tryCatchPattern":null,"preventionTips":["Use a NavigationPage for non-modal pushes on macOS.","Fall back to modals when a NavigationPage isn't present.","Route navigation through a platform-aware service."],"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"}