Skip to content
Source
Sign inSign up
TanStack/router

fix(react-router): stop lazyRouteComponent flashing the error component while reloading #8433

Openquanglam2807(GitHub profile, opens in a new tab)wants to merge 2 commits intomain fromrefs/pull/8433/headopened

Fixes #8377.

🎯 Changes

lazyRouteComponent already recovers from a stale chunk after a deploy: it sets a sessionStorage guard, calls window.location.reload() and suspends on a never-resolving promise.

But reload() is asynchronous and error is never cleared, so any render between the reload request and the document going away re-enters the if (error) branch, finds the guard key already set, and falls through to throw error. The route's errorComponent renders the import failure for a moment until the reload lands — and, for anyone wiring the router's defaultOnCatch to error tracking, the failure is reported as unhandled even though the user recovers.

This remembers the reload request in the closure and keeps suspending on later renders instead of re-evaluating the guard:

   let error: any
+  let reloadRequested = false
 
   const lazyComp = function Lazy(props: any) {
     if (error) {
+      if (reloadRequested) {
+        throw new Promise(() => {})
+      }
+
       if (isModuleNotFoundError(error) && ...) {
         const storageKey = `tanstack_router_reload:${error.message}`
         if (!sessionStorage.getItem(storageKey)) {
           sessionStorage.setItem(storageKey, '1')
+          reloadRequested = true
           window.location.reload()

The sessionStorage guard is deliberately untouched. It exists to stop a reload loop when a chunk is missing for some reason other than a new deployment, and it still does: the closure flag only covers renders within the page that is already reloading, so a fresh page load still surfaces the error.

Why this is worth fixing beyond the visual flash

Users do recover, so the flash is minor on its own. The problem is that a recovered failure becomes indistinguishable from an unrecovered one in error tracking. On one of our production apps this is the single largest source of client errors — ~400 events across ~93 issue groups (one per dead chunk URL, since the URL is in the message), at a deploy every 5–10 minutes. We spent a while assuming users were stranded on an error screen before the minified culprit frame showed they were being reloaded correctly the whole time. Details and breadcrumbs in #8377.

Tests

Added packages/react-router/tests/issue-8377-lazy-chunk-reload-reentry.test.tsx, following the existing issue-NNNN convention:

  • A render after the reload is requested keeps suspending instead of throwing, and does not trigger a second reload. Without the source change this fails with expected TypeError: Failed to fetch dynamically im… to be an instance of Promise.
  • A later page load with the guard already set still throws, so the anti-loop behaviour is not weakened. This passes both with and without the fix, on purpose.

Scope

React only. For reference, I checked the other two frameworks:

  • solid-router has the same re-entry: its reload branch returns { default: () => null } instead of throwing, but a second render still reaches throw error. I left it out to keep this reviewable and because I can't exercise it as confidently — happy to add it here or in a follow-up if you'd prefer it in one go.
  • vue-router already guards this with its attemptedReload closure flag, so it needs no change.

✅ Checklist

  • I have followed the steps in the Contributing guide.
  • I have tested code changes locally with the relevant test commands, or tests do not apply to this pull request.
  • I fully understand the code in this pull request, including any code generated with AI assistance.

Full @tanstack/react-router suite: 93 files, 1180 passed, 1 skipped, no type errors.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

  • Bug Fixes

    • Fixed lazy-loaded route failures during stale-chunk recovery so the error screen no longer briefly appears while a page reload is pending.
    • Prevented repeated reload requests during the same recovery attempt.
    • Preserved error reporting when the reload safeguard is already active.
  • Tests

    • Added regression coverage for reload behavior and subsequent error handling.
    1. Review Change StackReview Change Stack

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration

      Configuration used: Path: .coderabbit.yaml

      Review profile: CHILL

      Plan: Advanced

      Run ID: 4d68b52e-47a8-4dba-83d8-481e89a29d03

      📥 Commits

      Reviewing files that changed from the base of the PR and between 8e164d28f9e9eb1a7301109230d7ece9817492a8 and c6e404b8504d68d6f38a94bbce4a3c26f9dea4ef.

      📒 Files selected for processing (3)
      • .changeset/lazy-route-component-reload-reentry.md
      • packages/react-router/src/lazyRouteComponent.tsx
      • packages/react-router/tests/issue-8377-lazy-chunk-reload-reentry.test.tsx

      Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.


      📝 Walkthrough

      Walkthrough

      Changes

      Lazy route reload handling

      Layer / File(s)Summary
      Preserve pending reload state
      packages/react-router/src/lazyRouteComponent.tsx, .changeset/lazy-route-component-reload-reentry.md
      lazyRouteComponent records when it requests a reload and keeps suspending during subsequent renders. The changeset declares a patch release.
      Validate reload re-entry behavior
      packages/react-router/tests/issue-8377-lazy-chunk-reload-reentry.test.tsx
      Regression tests verify one reload request, continued suspension before document replacement, and error propagation when the session guard already exists.

      Priority: ➖ Normal

      Estimated code review effort: 2 (Simple) | ~10 minutes

      Change: Bug fix · Severity of issue fixed: Medium

      Merge Risk: ⚪ Minimal · up to c6e40

      The reload re-entry behavior and existing anti-loop guard are covered by the changed regression tests. No merge-blocking risk is identified.

      🚥 Pre-merge checks | ✅ 5
      ✅ Passed checks (5 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly and concisely identifies the primary change: preventing the lazyRouteComponent error component from flashing during reload.
      Description check✅ PassedThe description follows the required template, explains the motivation and implementation, documents testing and scope, completes the checklist, and includes release impact with a changeset.
      Linked Issues check✅ PassedIssue #8377 requires lazyRouteComponent to remain pending after it requests a stale-chunk reload, while preserving the sessionStorage anti-loop guard. The change adds the closure flag `reloadReque…
      Out of Scope Changes check✅ PassedThe changeset, the lazyRouteComponent update, and the regression tests all support Issue #8377. The changes do not add unrelated product behavior or unrelated files.
      Docstring Coverage✅ PassedDocstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (1 skipped: 1 …
      ✨ Finishing Touches
      🧪 Generate unit tests (beta)
      • Create PR with unit tests

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.
    2. I tested the change proposed here against @tanstack/react-router@1.170.46, after encountering the error-screen flash in our production app (my report is in #8377).

      Without the change, a second render after the reload request throws the import error. With it, subsequent renders remain suspended, only one reload is requested, and the existing guard still prevents a reload loop across page loads.

      I also applied it temporarily through pnpm in our TanStack Start app. The regression checks passed against both published runtime formats, and the app's production build succeeded with the fix included in the client bundle. I haven't verified the patched behavior across two real deployments, so this is local test and build confirmation rather than a production validation.

      @Sheraff @schiller-manuel is there anything blocking this fix, or any additional regression coverage you'd like? I can help with a focused follow-up if needed.

Sign in to join this conversation.