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.

[MILLERMARRU]

This is documented, just not obviously discoverable from the API reference alone. preloadRoute() doesn't resolve to undefined on a loader failure, it resolves with the array of RouteMatch objects and you're expected to inspect their status field. From the official preloading guide:

import { isNotFound } from '@tanstack/react-router'

const matches = await router.preloadRoute({ to: postRoute, params: { id: 1 } })

const routeFailure = matches?.find(
  (match) =>
    match.status === 'error' ||
    match.status === 'notFound' ||
    isNotFound(match.error),
)

if (routeFailure) {
  // inspect routeFailure.error
}

Combined with staleReloadMode: 'blocking' on route B's loader (which you already have), the promise really does settle only after the loader has actually run. preloadRoute() resolving to undefined in your testing is more likely from an edge case like the route not matching or an in-flight duplicate preload being short-circuited, not from the loader throwing. A thrown loader error still produces a match entry with status: 'error' in the resolved array rather than rejecting or emptying the whole preloadRoute() call.

So the deterministic gate you're after is: await preloadRoute(...), walk the returned matches for a failing status the way the snippet above does, and only call navigate() if none is found. No need to reach for route B's fetcher directly outside the loader.