RouterProvider inside Suspense shows hydrateFallback forever

[tommie-lie]

Reproduction

Go to https://codesandbox.io/p/devbox/lfpmvq?file=%2Fsrc%2FApp.jsx%3A36%2C28.
The site should say "Hydrating...", if not, try reloading a few times.

The error goes away if either:

• the loader in line 33 is slower, e.g. sleep(300)
• the component does not suspend, so the use(serviceDataPromise) line is commented out

System Info

System:
    OS: Linux 6.1 Debian GNU/Linux 12 (bookworm) 12 (bookworm)
    CPU: (2) x64 AMD EPYC
    Memory: 1.22 GB / 4.01 GB
    Container: Yes
    Shell: Unknown
  Binaries:
    Node: 20.12.0 - /usr/local/bin/node
    Yarn: 1.22.19 - /usr/local/bin/yarn
    npm: 10.5.0 - /usr/local/bin/npm
    pnpm: 8.15.6 - /usr/local/share/npm-global/bin/pnpm
  npmPackages:
    react-router: ^7.9.1 => 7.9.1 
    vite: ^6.0.3 => 6.3.5

Used Package Manager

pnpm

Expected Behavior

The AppRoutes component suspends and the user sees "Loading...". After 100ms the Promise resolves and AppRoutes renders a RouterProvider and all the loaders start running. While the loaders are running, the hydration fallback "Hydrating..." is shown.
After all loaders in the routes finish, the route's content should be displayed, in the MWE this would be Content.

Actual Behavior

In most cases (not consistent, as I suspect a race somehwere, but on my machine like 90% of the time), after the promise resolves and the router is rendered, I see "Hydrating..." forever and never the "Content".

In my real application, the loader actually loads data from the network and depending on how fast the request is, the application either works perfectly, or stalls forever. It took me a while to figure out that fast requests cause the application to fail ;-)

[brophdawg11]

fwiw you should be creating the router outside of render, but it looks like that doesn't solve the problem so I'll try to dig in when I get some time: https://codesandbox.io/p/devbox/dreamy-wing-forked-qhg854

[tommie-lie]

Out of curiosity: Until recently I had to conditionally create routes based on some state. I refactored the code enough to get rid of that and I can no create the router at the module level But what would be the correct way to pass conditional routes to createBrowserRouter if I can only determine the correct routes in a render because I need some React Context? Memoize the router?

[brophdawg11]

The correct way to add routes dynamically is patchRoutesOnNavigation, but yeah if you are forced to do it inside the router you want to memoize or use a ref so that you only ever create the router a single time.

[rzane]

We've also been seeing this issue pop up intermittently in our end-to-end test suites, and only in CI environments. We managed to get a reliable reproduction, but I don't think I'll be able to strip the reproduction case down enough to share it. We spent multiple days debugging, but this issue shed light on the problem, so thank you!

Here's what we were seeing:

1. This only ever affects the initial page load.
2. The loader function executes successfully, but the route component is never called.
3. The page continues to display the hydrate fallback element indefinitely.
4. Interestingly, calling .revalidate() on the router instance forces the page to render.

This is pretty much what we were doing:

const App = lazy(() => import("./App"));
const router = createBrowserRouter([ /* routes */ ]);

createRoot(element).render(
  <Suspense fallback={<Loader />}>
    <App router={router} />
  </Suspense>
);

Removing the <Suspense /> fixes the issue.