`router.navigate` hangs after `RouterProvider` unmount in tests (regression in ^1.170.19)

[Sachinvs23]

Which project does this relate to?

Router

Describe the bug

After upgrading from @tanstack/react-router@1.170.18 to @tanstack/react-router@1.170.19 and above, calls to router.navigate(...) can hang (the returned promise never resolves) in test environments when:

• A shared router instance has had a RouterProvider mounted at least once, and
• That RouterProvider has been unmounted (test cleanup), and
• A later test calls await router.navigate(...) while no RouterProvider is mounted.

On 1.170.18 the same test setup passes; on 1.170.19 the navigation promise never resolves and the test times out.

This is happening in a browser test setup (Vitest + Playwright + Chromium) where we:

• Create a single router instance via createRouter(...),
• Mount <RouterProvider router={router} /> in tests,
• Unmount via Testing Library/Vitest cleanup() after each test,
• Reuse the same router instance across tests.

Once a RouterProvider has been mounted and torn down, subsequent await router.navigate(...) calls when no provider is mounted hang on 1.170.19.

Complete minimal reproducer

https://github.com/Sachinvs23/React-router-navigate-hang

Steps to Reproduce the Bug

1. Clone the reproducer repo:

   git clone https://github.com/Sachinvs23/React-router-navigate-hang
   cd React-router-navigate-hang
   npm install
   

2. Ensure @tanstack/react-router is pinned to 1.170.19 in package.json.

3. Run the repro test:

   npm test -- src/router-regression.test.tsx
   

4. Observe:
   Test “primes RouterProvider once” passes.
   Test “navigates without provider after it was primed” hangs and times out (e.g. after 60s).

5. Change the router version to 1.170.18:
   "@tanstack/react-router": "1.170.18",

   Reinstall and re-run the same test file:

   npm install
   npm test -- src/router-regression.test.tsx
   

6. Observe:

   Both tests now pass; await router.navigate(...) resolves even when no RouterProvider is mounted.

Expected behavior

---

Expected behavior

I expected `router.navigate(...)` to:

- Resolve (or reject) promptly, even when no `RouterProvider` is currently mounted, **or**
- At least behave consistently between `1.170.18` and `1.170.19`.

In particular:

- With a shared router instance that has previously had a `RouterProvider` mounted and then unmounted,
- Calling `await router.navigate({ to: '/foo' })` while no provider is mounted should not hang forever.


### Screenshots or Videos

_No response_

### Platform

- TanStack Router:
  - @tanstack/react-router: 1.170.18 (works), 1.170.19 (hangs)
- React: 19.2.8
- Node: 24.13.1
- Bundler: Vite 8.2.1
- Test runner: Vitest 4.1.10 (browser mode with Playwright provider)
- Browser: Chromium (via Playwright in Vitest)
- OS: Windows 11


### Additional context

Additional observations:

- The router instance is shared across tests (`createRouter(...)` called once and exported).
- We mount `<RouterProvider router={router} />` in tests and unmount via Testing Library/Vitest `cleanup()` after each test.
- On 1.170.19, if we call `await router.navigate(...)` **before mounting a new RouterProvider** in a later test, the navigation promise never resolves.
- We instrumented the router with `router.subscribe('onBeforeNavigate'|'onLoad'|'onResolved'|'onRendered')` and wrapping `router.navigate`.
  - In the hanging case, we see `navigate start` and `onBeforeNavigate`, but `onLoad`, `onResolved`, and `navigate end` never fire.

Workarounds:

- If we always mount `<RouterProvider router={router} />` **before** awaiting `router.navigate(...)` in tests, the hang goes away.
- If we use a **fresh router per test** (calling `createRouter(...)` in `beforeEach` and passing it to `RouterProvider`), the hang also disappears.

Impact:

- This is a behavioral change between 1.170.18 and 1.170.19 and affects test setups that reuse a router instance and sometimes call `navigate` while the adapter is not currently mounted.

[Sheraff]

Do you have a non-test use-case for this issue?
And is there a reason you can't just re-mount the router in each test that uses navigate?

[Sachinvs23]

Thanks for looking into this.

I don't currently have a non-test use case that I can reproduce. The issue was discovered while upgrading our application from @tanstack/react-router@1.170.18 to 1.170.19 and above.

The reason we don't simply remount a fresh router in every test is that our test suite uses a shared application router and a common testUtils.render() helper. A large number of existing tests rely on this setup, so changing the router lifecycle for every test would require a broader test-infrastructure change.

The important behavior change we observed is:

• A shared router has RouterProvider mounted and then unmounted during test cleanup.
• A later test calls router.navigate() before mounting RouterProvider again.
• With 1.170.18, the navigation promise resolves.
• With 1.170.19+, the navigation promise can remain pending indefinitely and eventually time out.

I also confirmed that using a fresh router per test, or mounting RouterProvider before calling router.navigate(), avoids the hang.

If this behavior is intentional and router.navigate() is not expected to be used while the router has no mounted RouterProvider, could you please recommend the preferred testing approach for this scenario?

In particular, should we:

1. create a fresh router for each test,
2. always mount RouterProvider before calling router.navigate(), or
3. use some other recommended router/test lifecycle pattern?

That guidance would help us update our shared test utilities correctly rather than applying a workaround to individual tests.

[Sheraff]

This behavior is intentional, i just didn't think it would impact anyone. and doing the full clean up on unmount would add bytes to the client that is never needed (or maybe there are use-cases i've never heard of yet, which is why I was asking).

I would recommend creating a fresh router for every test, this avoids leaking state from one test to another. I think isolation is usually a good practice for testing anyway.