Troubleshooting¶
"PlayxNavigation is not initialized"¶
You used PlayxNavigation before it was booted. Wrap your app in
PlayxNavigationBuilder(router: router, ...), or call await PlayxNavigation.boot(router: router)
before using it. See Installation and setup.
A page shows its loading widget forever¶
onEnter never finishes or the page is waiting for boot.
- Set
enterTimeoutand anerrorBuilderto see what happens (Error handling). Without anerrorBuilder, errors are reported withFlutterError.reportError: check your logs. - Pages wait for every
onInitApp. If one never completes, or boot was never called, no page enters.await PlayxNavigation.ensureInitializedcompletes when boot finished. - Make sure every code path of
onEntercompletes (no un-awaited completer).
"No X found for this page" (StateError)¶
PlayxView<X> or context.controller<X>() did not find a controller of that type. Either:
- declare it:
PlayxRoute<X>(controller: ...), - store it from the binding:
PlayxScope.of(context).put<X>(...), - or configure
PlayxPageConfig.findControllerif it lives in a registry (GetX and other registries).
Also check the widget is below the page. Dialogs and bottom sheets need
PlayxScopeProvider. In a shellBuilder or initBuilder
the controller may not exist yet: use context.maybeController<X>().
onExit runs after onReEnter¶
This is intended: when a page is popped, the revealed page re-enters immediately and the popped page
exits when its animation ends (lifecycle guarantees). If two pages share
one resource, key it by PlayxScope.id or guard cleanup with activeScopes.isEmpty.
A controller was deleted while a page still used it¶
Two live pages share a global registration (for example Get.put without a tag, for two stacked
details pages). Tag registrations with PlayxScope.of(context).id, keep the controller in the
scope, or use a route controller.
state.extra is null on web¶
It is not part of the URL, so it is lost on refresh, typed or shared URLs and deep links. Load by id
when it is missing and use state.extraAs<T>() to read it safely (Web).
There is no back button on a page opened by URL¶
Flutter's automatic AppBar back button only appears when there is something to pop. Use
PlayxBackButton and a route parentLocation where needed (Web).
The browser tab title resets¶
MaterialApp sets its own title whenever it rebuilds. Return PlayxNavigation.pageTitle from
onGenerateTitle (Browser tab titles).
await PlayxNavigation.offAndTo(...) never finishes¶
The returned future completes when the new page is popped, like to. Don't await it to wait for the
navigation itself (Navigation API).
Lifecycle callbacks don't fire for dialogs or Navigator.push¶
Only router navigation (pages in go_router's stack) affects the lifecycle. Dialogs, bottom sheets and
routes pushed with Navigator.push don't hide the page underneath.
Changing a query parameter doesn't re-run onEnter¶
Only the path identifies a page. Changing the query string keeps the same page. Read parameters in
the widget from GoRouterState, or navigate to a different path.
Hot reload doesn't re-run onInitApp¶
onInitApp runs at boot. Use a hot restart after changing it.
Dependency conflict with go_router¶
3.0 depends on go_router: ^17.5.0. go_router 18 raises the minimum SDK to Flutter 3.44 and moves to
material_ui / cupertino_ui; support for it will come in a later release.
Still stuck?¶
Open an issue with a minimal router that reproduces it: github.com/playx-flutter/playx_navigation/issues.