| name | uno-navigation-troubleshooting |
| description | Troubleshoot common issues with Uno Platform Navigation Extensions. |
| when_to_use | Use when navigation is not working or throwing errors, pages not loading or blank screens, back navigation not working as expected, region-based navigation issues, route registration errors, or shell.xaml / ExtendedSplashScreen initialization issues. |
| metadata | {"author":"uno-platform","version":"2.3","category":"navigation"} |
Uno Navigation Troubleshooting — Agent Skill
Workflow
Docs lookup: call uno_platform_docs_search(...) first, then uno_platform_docs_fetch(sourcePath="…") using the sourcePath field from a result (a relative .md path; add the result's anchor for a section). Never pass a URL, a .html link, or a hand-built path.
Step 1: Search for Navigation Troubleshooting
uno_platform_docs_search("Uno Navigation troubleshooting errors common issues")
Step 2: Check Common Pitfalls
Fetch the regions how-to page for critical warnings:
uno_platform_docs_fetch(sourcePath="external/uno.extensions/doc/Learn/Navigation/HowTo-Regions.md")
Step 3: For Route Registration Issues
uno_platform_docs_search("Uno Navigation route not found register ViewMap DataViewMap")
Step 4: For Advanced Navigation Issues
uno_platform_docs_fetch(sourcePath="external/uno.extensions/doc/Learn/Navigation/Advanced/HowTo-AdvancedPageNavigation.md")
Common Issues (Stable Reference)
- Region.Attached in Shell.xaml: NEVER use
Region.Attached="True" inside Shell.xaml or ExtendedSplashScreen content — navigation host isn't ready yet
- Missing route registration: All pages must be registered via
ViewMap/DataViewMap in RegisterRoutes
- Missing UnoFeatures: Ensure
Navigation;Toolkit are in <UnoFeatures>
- Missing XAML namespace:
xmlns:uen="using:Uno.Extensions.Navigation.UI" required for regions and attached properties
- Back stack issues: Use qualifiers (
-/ or Qualifiers.ClearBackStack) to manage back stack
- Data not arriving: Ensure
DataViewMap is registered for the data type, and ViewModel accepts data via constructor
Related Skills
- [[uno-navigation-setup]] — Proper setup
- [[uno-navigation-regions]] — Region configuration
- [[uno-navigation-routes]] — Route registration