Trace the route, not the symptom

Turn on route diagnostics

Enable debugLogDiagnostics while developing. Use logs to compare the destination you requested with the route map you actually registered. Avoid logging complete user URLs if they can contain sensitive query values.

Narrow the failure

Does the problem happen before matching, during redirection, while building a screen, or only after browser reload? A route that works through a button but fails after refresh often points to hosting rather than the route builder.

Check shell ownership

When a page appears underneath a tab bar instead of above it, inspect the Navigator keys and parentNavigatorKey. When a tab loses state, check whether the design uses separate stateful branches and whether keys or router instances are being recreated.

Reduce before reporting

Build the smallest route tree that still fails. Record package and Flutter versions, entry URI, steps, expected behavior, and actual behavior. Remove tokens and private data before attaching logs to an upstream issue.

final router = GoRouter(
  debugLogDiagnostics: true,
  routes: routes,
  errorBuilder: (context, state) => UnknownLocationScreen(
    message: 'This location is not available.',
  ),
);