Loader receives stale `params._splat` on first navigation with splat routes

[thuillart]

Which project does this relate to?

Router

Describe the bug

When using a splat route (/$) with params._splat, navigating between routes requires two clicks to update the loader data. On the first click, the URL updates correctly but the loader runs with stale params._splat from the previous route, causing Route.useLoaderData() to return data for the wrong route.

Your Example Website or App

https://github.com/thuillart/site.git

Steps to Reproduce the Bug or Issue

1. Go to /readings
2. Click on /ai
3. Actual: data still shows /readings
4. Click again → data shows /ai

Expected behavior

As a user, I expected: When I click a link to navigate from /docs/a to /docs/b, the page should immediately show the content for /docs/b with the correct loader data.

But I am seeing: When I click a link to navigate from /docs/a to /docs/b, the URL updates to /docs/b but the page still displays content from /docs/a. I need to click the link a second time (or navigate to another route) before the correct content for /docs/b appears.

Screenshots or Videos

1. Go to /readings
2. Click on /ai
3. Actual: data still shows /readings
4. Click again → data shows /ai

Platform

• Router / Start Version: 1.154.7
• OS: macOS
• Browser: Chrome
• Browser Version: 144.0.7559.60
• Bundler: vite
• Bundler Version: 7.3.1

Additional context

• Works correctly in @tanstack/react-router@1.153.1
• Broken in @tanstack/react-router@1.153.2 and later
• The loader is being called but receives stale params._splat on first navigation
• The URL and Route.useParams() update correctly, but the loader receives stale params
• This affects any route that depends on params._splat in the loader

I also opened an issue in Fumadocs where it was determined this is likely a TanStack Router issue rather than a Fumadocs issue.

[thuillart]

After investigating PR #6398 ("refactor: don't reparse upon navigation"), introduced in 1.153.2, I found something interesting:

The snapshot validation in matchRoutes checks if the snapshot exists, has route IDs, and if those IDs are valid. However, it doesn't verify that the snapshot's params match the current pathname.

For splat routes like /$, both /readings and /ai share the same route ID (['/$']), so the validation passes for either snapshot even when the params differ. When navigating from /readings to /ai, if a stale snapshot from the previous route is present, the validation passes and the code uses the cached params instead of re-parsing from the current pathname.

The snapshot is read from this.latestLocation.state.__TSR_matches in beforeLoad, then passed to matchRoutes where it gets validated. Since the validation only checks route IDs and not whether the params match the current pathname, a stale snapshot can pass validation and cause the loader to receive params from the previous route.

A potential fix would be to also verify that the snapshot's params match what would be extracted from the current pathname before using it, or to only use snapshots for back/forward navigation (POP) as the comments (in the PR) suggest they're intended for.

[schiller-manuel]

we reverted #6398 and will revisit this perf optimization at a later point