Flutter: Want to disable automatic routing of go_router in app

by

Summary

The developer attempted to disable the default routing behavior in go_router by returning null in the redirect callback. While this stops navigation, it breaks the router’s internal state, likely causing the errorBuilder to trigger because the router cannot resolve a valid destination for the initial location. The correct approach to “disable” automatic routing isn’t to intercept every path and return null, but to define a “catch-all” route to capture deep links manually, or simply remove the routes definitions if the app is a single-page widget.

Root Cause

The root cause is a misunderstanding of the redirect callback’s contract in go_router.

  1. The null Trap: Returning null in redirect is a valid return type, but it signals to the router: “I have decided not to redirect, so please proceed to render the route requested.” However, if the requested route doesn’t match any defined GoRoute (or matches a route that throws an error during building), the router defaults to the errorBuilder.
  2. Initial Location Mismatch: When initialLocation: '/' is set, the router tries to resolve it. If the redirect returns null but the subsequent route resolution fails (perhaps due to missing route definitions or logic inside the splash screen), errorBuilder is invoked.
  3. Missing “No-Op” Route: To effectively disable routing and show a specific “manual” screen, the developer needs a catch-all route (e.g., path: '/') that returns the desired widget. Without this, and with a blocking redirect, the router is left in an ambiguous state.

Why This Happens in Real Systems

  • Misinterpretation of “Disabling”: Developers often confuse “disabling automatic redirection” with “stopping navigation entirely.” In state management/navigation libraries, “disabling” usually means taking control of the flow, not halting it.
  • Router as a State Machine: go_router is a finite state machine. If you feed it a state (URL) and intercept the transition logic to return null, you leave the machine in a limbo if the target state isn’t explicitly handled by the routes list.
  • Deep Linking Complexity: When handling deep links manually, developers often think they need to block the router before it loads. However, the router usually needs to capture the deep link parameters first, then allow the developer to process them. Blocking the entry completely usually results in an empty or error state.

Real-World Impact

  • Broken User Experience: Users attempting to open the app via a deep link or directly will see an ErrorScreen immediately, creating a hostile first impression.
  • Navigation Lock-in: The app might get stuck on the error screen because the navigation stack is malformed. The user cannot navigate “back” because the router state is invalid.
  • Developer Velocity Loss: Debugging router state is notoriously difficult. This issue leads to hours of tweaking redirect logic rather than fixing the architectural approach to routing.

Example or Code

To handle deep links manually while avoiding the error screen, you must allow the router to capture the path but handle the UI logic yourself. Here is the correct configuration to achieve “manual” handling:

final GoRouter routes = GoRouter(
  navigatorKey: _rootNavigatorKey,
  initialLocation: '/',
  // Remove the errorBuilder unless you truly expect errors
  // errorBuilder: (context, state) => ErrorScreen(),

  // Do NOT use a blanket return null here if you want to intercept deep links.
  // Instead, use a redirect that checks for specific conditions.
  // If you truly want to ignore routing and just show the splash screen
  // regardless of the URL, do not rely on redirect. Just use a catch-all route.

  routes: [
    // This is the "Catch-All" or "Manual Handling" route
    GoRoute(
      path: '/:_(.*)', // Matches any path
      builder: (BuildContext context, GoRouterState state) {
        // You have full access to the deep link info here via `state.location`
        // Now you can decide manually what to do.
        return SplashScreen(
          // Pass deep link params if needed
          deepLinkPath: state.location, 
        );
      },
    ),
  ],
);

How Senior Engineers Fix It

  • Architectural Separation: Seniors decouple “Navigation” from “Business Logic.” They don’t try to break the router; they make the router a dumb conveyor belt that always lands at a “Handler” widget.
  • Single Entry Point: They configure a single route (often path: '/' or a wildcard /:_(.*)) that acts as the gatekeeper. All deep links land here.
  • Internal State Management: Inside that SplashScreen (or HomeScreen), the Senior Engineer uses a useEffect or initState to check the incoming deep link data.
    • If it’s a valid deep link -> context.go('/target').
    • If it’s an invalid state -> Show error UI inside the widget, not via the router’s errorBuilder.
  • Validation Layer: They implement a middleware (or a complex redirect logic) that validates the route but returns the original path if validation passes, allowing the routes list to handle the rendering.

Why Juniors Miss It

  • Procedural Thinking: Juniors often think in linear steps: “Stop the router -> Check link -> Navigate.” They don’t account for the event-loop and lifecycle of the widget tree where the router must resolve to a widget immediately.
  • Fear of Routes: They try to avoid defining routes for deep links because they think defining a route implies automatic navigation. They don’t realize a route is just a definition of what widget to show, not when to show it.
  • Over-reliance on redirect: redirect feels like an “event handler” to juniors. They use it for logic that belongs in widget lifecycle methods (like initState).