Params parse/stringify behavior doesn't match types when narrowing params

[pawelblaszczyk5]

Which project does this relate to?

Router

Describe the bug

Hello 👋

If I use params.parse to narrow valid param value (my exact use case is language in URL and narrowing valid values only to "en" and "pl", my use case also involves parsing them into "en-US" and "pl-PL" but I narrowed the issue down) these are narrowed both in stringify function and everywhere where I can provide a value for it (e.g. Link or redirect or navigate).

However, the reality is that stringify function (where types says that it's only called with one of narrowed values) is also called with invalid values when they're visited. You can see, even TypeScript complaining that it never happens.

Is this expected behavior? I tried to look into the code, but I couldn't fully grasp why stringify is called if params were never parsed in the first place. Is notFound allowed to be called like this in params.parse?

While debugging I also spotted one more thing - stringify behaves weirdly if error is thrown inside. Blank page is rendered and no log to be found anywhere. I stumbled upon it cause I used Effect schema, which threw error in stringily when I tried to decode "en-US" or "pl-PL" into "en"/"pl", because it was actually getting different value sometimes.

Your Example Website or App

https://github.com/pawelblaszczyk5/tanstack-router-not-found-params-problem

Steps to Reproduce the Bug or Issue

1. Create params.parse function in route with path param that narrows string value into set of allowed values, otherwise throws notFound (or redirect - it also works in that case)
2. Create params.stringify where types say it'll only ever be called with one of narrowed values
3. Observe it being called also with values that weren't parsed correctly

Expected behavior

Types match the runtime behavior. Probably stringify is never called with value that wasn't properly parsed?

Screenshots or Videos

Provided them above in description

Platform

• Router / Start Version: 1.145.7
• OS: macOS
• Browser: Reproducible everywhere
• Browser Version: Same
• Bundler: Vite
• Bundler Version: 7.2.7

Additional context

No response

[pawelblaszczyk5]

What I also found is that in that case if (notFound) is rendered on the same route that has this param, useParams from that route can be called - won't throw, and its type will just lie