fix(router-core): buildLocation should interpolatePath w/ stringified params for skipRouteOnParseError routes

[Sheraff]

Fixes #6490

Warning

I'm not 100% convinced this is a good idea.

Possible issues:

• slower than not doing it
• sometimes people pre-interpolate their to props, and then it wouldn't match anything in the routesByPath lookup
• sometimes once interpolated, the pathname will actually match another route than the original to (intended behavior) but by then we will have stringified the params using the original to (weird behavior?)
• aren't there other places in the codebase where we just encodeURIComponent the params instead of going through params.stringify? I have a hard time believing we always know which route branch we're working on
• ??

However, if you respect the types, and you don't have a crazy route setup that makes conflict likely, then this is pretty powerful (see original issue).

The alternatives are:

• to simply forbid the combined use of skipRouteOnParseError.params: true and params.stringify
• to use a separate method for skipRouteOnParseError.params than the one used for "reversing the stringification"

🤷

Summary by CodeRabbit

• New Features

  • Route-building utility is now publicly available for external use.

• Improvements

  • Improved path interpolation when route parameters use custom parse/stringify, ensuring correct pathname output even when parse errors are configured to skip a route.

• Tests

  • Added tests covering parameter stringification and skip-on-parse-error behavior to validate route resolution outcomes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Exports buildRouteBranch from the route-tree module and adds a pre-interpolation parameter stringification pass in buildLocation (using route branch stringifiers) with new tests covering skipRouteOnParseError behavior.

Changes

Cohort / File(s)	Summary
Route Tree Module Export packages/router-core/src/new-process-route-tree.ts	Adds export to buildRouteBranch, making it part of the module's public API.
Parameter Stringification Preprocessing packages/router-core/src/router.ts	Imports buildRouteBranch and introduces prestringifiedParams flow: pre-stringify params across a route branch when skipRouteOnParseError.params is set, use those params for interpolatePath, and fall back to recomputing stringification when destination mismatches.
Test Coverage packages/router-core/tests/build-location.test.ts	Adds tests validating buildLocation yields expected pathname with custom parse/stringify and skipRouteOnParseError configured for params.

Sequence Diagram(s)

sequenceDiagram
  participant Router as Router.buildLocation
  participant Branch as buildRouteBranch
  participant Route as Route.stringify
  participant Interp as interpolatePath
  participant Dest as DestinationResolver

  Router->>Branch: request branch for target route
  Branch-->>Router: route branch (stringifiers)
  Router->>Route: apply stringify across branch -> prestringifiedParams
  Route-->>Router: prestringifiedParams
  Router->>Interp: interpolatePath(nextTo, prestringifiedParams, decoder)
  Interp-->>Router: interpolatedNextTo
  Router->>Dest: resolve destination with interpolatedNextTo
  Dest-->>Router: resolved destination (fullPath)
  alt destination matches trimmed target
    Router->>Router: use interpolatedNextTo as nextPathname
  else destination mismatch
    Router->>Route: compute stringifiedParams fallback
    Route-->>Router: stringifiedParams
    Router->>Interp: interpolatePath(nextTo, stringifiedParams)
    Interp-->>Router: nextPathname
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• refactor(router-core): skip full matchRoutesInternal for Link's buildLocation, use simple getMatchedRoutes #6445: Modifies buildLocation interpolation/path resolution logic in router.ts, overlapping with the new prestringification changes.
• refactor(router-core): cache matched route branch alongside the rest of the route match #5882: Introduced an internal buildRouteBranch helper in the route-tree module that this change now exports and reuses.
• refactor(router-core): reduce buildLocation object allocations #4981: Previously adjusted buildLocation param handling and in-place nextParams mutation, touching related logic paths.

Suggested reviewers

• schiller-manuel
• nlynzaad

Poem

🐰 I hopped the branch and called each name,
I dressed the params before the game,
So paths sing true and routes align,
I tuck their strings, one hop in time,
Hooray — the URL looks fine! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the primary fix: buildLocation now uses stringified params when interpolating paths for routes with skipRouteOnParseError configuration.
Linked Issues check	✅ Passed	The PR directly addresses issue #6490 by implementing the required fix: stringified params are now applied during interpolatePath for skipRouteOnParseError routes, preserving custom parse/stringify flows.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing the skipRouteOnParseError stringification issue: exporting buildRouteBranch, implementing prestringifiedParams logic in buildLocation, and adding comprehensive test coverage.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 6f09b9f

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	9m 17s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	1m 41s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-01-24 17:22:52 UTC

[pkg-pr-new]

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsc
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@6491

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@6491

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@6491

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@6491

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@6491

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@6491

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@6491

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@6491

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@6491

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@6491

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@6491

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@6491

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@6491

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@6491

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@6491

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@6491

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@6491

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@6491

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@6491

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@6491

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@6491

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@6491

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@6491

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@6491

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@6491

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@6491

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@6491

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@6491

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@6491

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@6491

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@6491

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@6491

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@6491

@tanstack/vue-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router@6491

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-devtools@6491

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-ssr-query@6491

@tanstack/vue-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@6491

@tanstack/vue-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-client@6491

@tanstack/vue-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-server@6491

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@6491

commit: 6f09b9f

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/router-core/src/router.ts`:
- Around line 1803-1807: The interpolatedNextTo is currently built from
nextParams (parsed values) but later code sometimes needs the stringified values
in prestringifiedParams; change the interpolation so that when
prestringifiedParams is provided you call interpolatePath with params:
prestringifiedParams (and same decoder) instead of nextParams, or alternatively
compute a second value (e.g., interpolatedPrestringifiedNextTo) by calling
interpolatePath({ path: nextTo, params: prestringifiedParams, decoder:
this.pathParamsDecoder }) and use that result wherever the code currently
branches on prestringifiedParams (including the return path and any route
matching that relies on interpolatedNextTo). Ensure the unique symbols involved
are interpolatePath, interpolatedNextTo (or new
interpolatedPrestringifiedNextTo), nextParams, and prestringifiedParams so the
correct interpolated pathname is returned and used for matching.