Deterministic way to gate navigation on preload success?

[Nandan1996]

Hi folks, we are working through a checkout-style flow and wanted to check if there is an intended pattern for this.

Our goal is:

• from route A, preload route B
• navigate only if route B loader succeeds
• then reuse that result on enter

We found that the immediate enter refetch is handled by setting a staleTime, so that part is OK.

What we are still missing is a deterministic success or failure signal from preloadRoute() itself.

staleReloadMode: blocking helps because preload waits for the loader promise to settle, but if the loader throws, preloadRoute() seems to return undefined, and we could not find a clean API to know whether route B loader actually succeeded or failed before deciding to navigate.

Is there a first-class TanStack Router way to gate navigation on preload success, without directly calling route B fetcher outside the loader?

[Nandan1996]

Hey @tannerlinsley @schiller-manuel ,
Although this is not a blocker for us and there are ways to get around this, but trying to figure out a better approach.
Thank you.

[schiller-manuel]

we could make preloadRoute throw when a specific option is set.

[schiller-manuel]

eg like this #7031

[Nandan1996]

Took a look at the PR diff and this looks very useful for the cold/blocking preload path.

One thing I think is still worth calling out: this doesn’t seem to fully solve the warm stale preload case when the loader is allowed to reload in background.

From what I can tell, the existing handleLoader branch for:

• loaderShouldRunAsync
• !inner.sync
• shouldReloadInBackground

is unchanged, and that branch still runs runLoader(...) inside an async IIFE that only handles redirects in the catch block.

So my reading is:

• cold preload + throwOnError: true => good, caller should get the error
• preload with staleReloadMode: 'blocking' + throwOnError: true => good, caller should get the error
• warm stale preload with default background stale reload => still not deterministic, because preloadRoute() may resolve before that async reload finishes, and non-redirect errors can still be swallowed from the caller POV

If that reading is correct, then throwOnError definitely improves things, but consumers who want to gate navigation on preload success would still need staleReloadMode: 'blocking' (or equivalent) for deterministic behavior.