[go_router] Fix assertion failure when onException fires on initial navigation

[davidmigloz]

When onException is provided and fires during the initial navigation (e.g. a deep-linked route blocked by onEnter returning Block.stop()), parserExceptionHandler in router.dart returns routerDelegate.currentConfiguration. On the initial navigation nothing has committed yet, so that configuration is empty, and GoRouterDelegate.setNewRoutePath crashes on assert(configuration.isNotEmpty || configuration.isError).

Crash sequence:

1. App starts with initialLocation pointing at a route.
2. onEnter returns Block.stop() for it.
3. The parser builds an error RouteMatchList containing BlockedInitialNavigationException (isError == true) and invokes onException.
4. parserExceptionHandler synchronously returns routerDelegate.currentConfiguration — still empty.
5. setNewRoutePath asserts configuration.isNotEmpty || configuration.isError — neither holds — crash.

The fix has two parts:

1. router.dart: fall back to the error match list when the current configuration is invalid — neither non-empty nor isError — satisfying the assertion's isError branch.
2. parser.dart: in the onCanNotEnter no-prior-route branch, defer the onParserException call to a microtask (the same pattern as the existing deferral for the onEnter then callback nearby). Without this, a recovery navigation made synchronously inside onException — e.g. router.go('/fallback'), as in the issue's repro — is silently discarded by the Router's intent-token churn, leaving the app parked on the error state. Deferring past the in-flight parse lets synchronous recovery work the way onException normally does.

Behavior is unchanged everywhere else: non-initial navigations return the non-empty currentConfiguration as before, the plain unmatched-initial-route path keeps its fully synchronous onException call (existing redirect tests depend on it, and that path never drops the re-entrant navigation), and without onException neither code path is reached.

Tests in exception_handling_test.dart:

• One test calls router.go('/fallback') synchronously from inside onException and asserts full recovery (fallback rendered, protected absent, router.state.uri.path == '/fallback'); a second drives the app-side deferred-via-scheduleMicrotask pattern. Verified red/green for each half: without the router.dart fallback the delegate assertion fires at delegate.dart:221; without the parser.dart deferral the synchronous recovery is silently dropped and the fallback never renders.
• The router.dart fallback is also covered independently of the deferred path. An unmatched initial navigation with a non-navigating onException now renders the default error screen; before the fix the app just stayed blank, because the empty current configuration hit setNewRoutePath's equality early-return. And a second unmatched navigation no longer replaces the first installed error configuration: the fallback preserves any valid current configuration, whether non-empty or isError.

Validated after rebasing onto current main (go_router 18.0.2):

• flutter test test/exception_handling_test.dart (10 tests)
• Package and example test suites on the VM, Chrome, and Chrome/Wasm (456 package tests and 17 example tests per platform; 2 existing package tests skipped)
• Repository format, analyze, validate, and publish dry-run checks

Fixes flutter/flutter#189582

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under¹.
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under¹.
• All existing and new tests are passing.

Footnotes

1. Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩²

[tarrinneal]

From traige: Is this pr still being worked on?

[davidmigloz]

Yes, thanks for the ping. I have rebased this onto current main (go_router 18.0.2), resolved the intervening test-import migration, rerun the package and example suites on the VM, Chrome, and Chrome/Wasm, and refreshed the description. I am marking it ready for review now.

[gemini-code-assist]

Code Review

This pull request defers the execution of onParserException using a microtask in GoRouteInformationParser to prevent recovery navigations from being discarded during an initial parse. Additionally, it updates parserExceptionHandler in GoRouter to fall back to the error match list when the current configuration is empty and not an error, preventing an assertion failure in GoRouterDelegate.setNewRoutePath. Relevant unit tests and a changelog entry have been added. There are no review comments, so no further feedback is provided.