fix(router): patch router-core so evicting an in-flight preload doesn't TypeError

[dawsontoth]

Fixes #1387.

What

Datadog RUM has been recording a handled TypeError: Cannot read properties of undefined (reading '_nonReactive') from router.preloadRoute — escalated to 10 occurrences across 8 sessions in a day, across many routes.

Root cause (upstream, TanStack/router#7759): several code paths in @tanstack/router-core's load-matches.js re-look up the match with getMatch(matchId) after an await and dereference ._nonReactive without a guard. A preload's match only lives in cachedMatches, so if the user navigates (or router.invalidate() / cache GC runs) while a hover-intent preload is in flight, the match is evicted, getMatch() returns undefined, and preloadRoute console.errors the TypeError — which RUM picks up on every hover-then-navigate race.

We're already on the latest published versions (react-router@1.170.17 / router-core@1.171.14); no released version contains a fix. Upstream has two open fix PRs (#7003, #7006).

How

• patches/@tanstack__router-core@1.171.14.patch (pnpm patchedDependencies): ports upstream PR #7003. A missing match during load now throws an internal MatchLoadCancelledError that resolves the evicted match's controlled promises and aborts it; preloadRoute swallows it (the preload becomes a quiet no-op). The background stale-reload cleanup also no longer assumes the match still exists. Patched in both dist/esm and dist/cjs.
• src/router/__tests__/preloadEvictionRepro.test.ts: regression tests that reproduce the exact production error against the unpatched package (cache GC and invalidate() during an in-flight preload) and pass with the patch.
• CLAUDE.md: documents the patch and what to do on the next router bump (check whether upstream shipped the fix; otherwise re-create the patch — pnpm will hard-error on the version mismatch, so it can't be silently lost).

Verification

• New regression tests fail on unpatched router-core with the exact production TypeError, pass with the patch.
• Full suite: 192 test files / 1266 tests pass; lint + tsc clean.
• Live app (worktree dev server on 5173): confirmed the patched code is what Vite serves, then stress-tested hover-preload → navigate → back races across links — zero console errors/warnings.

Drop the patch once upstream ships the fix.

🤖 Generated with Claude Code

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[dawsontoth]

/gemini review

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[kriszyp]

Good instinct putting a version guard on this — patching router-core internals is exactly the kind of thing that should fail loudly on a dependency bump rather than silently stop applying.

One thing worth fixing before merge: in the "else" branch of the patch (patches/@tanstack__router-core@1.171.14.patch:76, mirrored at the esm build :236), cleanupMatch isn't reassigned after the second getMatchOrThrowCancelled call. Trigger: a second concurrent load of the same match is already in flight (prevMatch._nonReactive.loaderPromise truthy) when the cache evicts that match during the subsequent await — the eviction's own cleanup step gets skipped in that branch.

Smaller one: the err instanceof MatchLoadCancelledError checks are per-module-format (cjs/esm each define and check their own class). Not a live bug given the current install topology, but if pnpm/Vite ever resolve two separate instances of router-core (a dual-package hazard), the check silently falls through to generic error handling instead of the cancellation path. A err?.name === 'MatchCancel' fallback would be cheap insurance — low priority, not blocking.

— KrAIs

[dawsontoth]

@kriszyp Both addressed in 5a19ed4:

• cleanupMatch gap in the concurrent-load branch: confirmed — with prevMatch._nonReactive.loaderPromise in flight, cleanupMatch was still undefined at the post-await getMatchOrThrowCancelled, so an eviction there threw without resolving the evicted match's controlled promises. Now cleanupMatch = prevMatch is assigned as soon as prevMatch is fetched (ESM + CJS), so that branch cleans up like the others. Added a regression test that drives exactly that branch (second preload of the same route joining the first's in-flight loader, then clearExpiredCache() mid-await) and asserts both preloads settle with no console errors. Worth noting this deviates from upstream PR #7003, which has the same gap — I'll flag it there.

• instanceof under a dual-package hazard: isMatchLoadCancelledError now falls back to err instanceof Error && err.name === 'MatchCancel' in both module formats.

🤖 Addressed by Claude Code