[Start] ssr: false hydration can throw undefined when a pending match loses its loadPromise #7910
Send to my agentWhich project does this relate to?#
TanStack Start / React Router
Describe the bug#
During the initial hydration of a route with ssr: false, React can render a
stale match snapshot whose status is still pending after the router has
already cleared the match's non-reactive loadPromise.
MatchInnerImpl then executes:
if (match.status === 'pending') {
throw getMatchPromise(match, 'loadPromise')
}
getMatchPromise(...) returns undefined, so React receives
throw undefined. The route error boundary cannot render a useful error and
the thrown value reported by React is literally undefined.
We instrumented the router state synchronously from React's onCaughtError
callback and captured this state at the time of failure:
{
"routeId": "/example",
"status": "pending",
"isFetching": false,
"hasLoadPromise": false,
"hasMinPendingPromise": true,
"hasDisplayPendingPromise": false,
"error": { "type": "undefined" }
}
The component stack starts at MatchInnerImpl / Match. Shortly after the
failure, inspecting the router shows the match as success.
No document or static asset requests fail. The server bootstrap data contains
the leaf match as pending with ssr: false.
This appears to mix two points in time:
statuscomes from the reactive match snapshot retained by a concurrent React render;loadPromiseis read from the router's current_nonReactivestate bygetMatchPromise.
The current router state has already removed loadPromise, while React is
still rendering the older pending snapshot.
Reproduction shape#
The affected route has this shape:
const RouteView = lazyRouteComponent(
createClientOnlyFn(() => import('./route-view')),
)
function Component() {
return <RouteView />
}
Object.assign(Component, {
preload: RouteView.preload,
})
export const Route = createFileRoute('/example')({
ssr: false,
pendingComponent: Pending,
component: Component,
})
Forwarding the lazy component's .preload() causes the server bootstrap match
to be serialized as pending. The issue is timing-sensitive and is easier to
reproduce in a larger nested route tree during concurrent hydration.
Expected behavior#
A match rendered with status: 'pending' should always have a valid thenable
available to suspend on. Router state should not allow MatchInnerImpl to
execute throw undefined.
Possible approaches might be to keep loadPromise stable until no reactive
pending snapshot can observe the match, or to read the status and promise
from a consistent snapshot.
Platform#
@tanstack/react-router: 1.170.16@tanstack/router-core: 1.171.13@tanstack/react-start: 1.168.26- React / React DOM: 19.2.4
- Browser: Chrome
- OS: macOS
Additional context#
The relevant source paths appear to be:
packages/react-router/src/Match.tsx: thestatus === 'pending'branch andgetMatchPromisepackages/router-core/src/load-matches.ts: resolving and clearing_nonReactive.loadPromise
The same getMatchPromise / throw pattern is still present on the current
main branch.
schiller-manuel(GitHub profile, opens in a new tab) added labelsinformation needed
I’ll try to figure out a better way to present this demo. To be honest, my project is quite large, and that might be exactly why this edge case occurred. So it might take some time to put together a minimal, reproducible demo.
However, I can share some information in advance:
- We didn’t actually use
Object.assignon any component; we just wanted to illustrate that the issue is related to thepreloadfield, and that hiding thepreloadfield using an intermediate component can resolve the crash. - Not all cases where
ssr: falseis set will cause problems. - Switching to “data only” mode also resolves this issue.
- We didn’t actually use
please also try with latest start version
closing as no reproducer was provided. please open a new issue if this can be reproduced properly
Sign in to join this conversation.
please provide a complete reproducer project as a github repo
this here:
is incorrect usage. please provide a reproducer that doesn't abuse the API.