TanStack / TanStack/router

Hydration error on direct navigation to non-root routes in SPA mode

Open
#6,455 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
15.1k
Forks
1.9k
Avg merge
1d 20h
Merged PRs (30d)
143

Description

Which project does this relate to?

Start

Describe the bug

When deploying a TanStack Start application with spa mode enabled to Cloudflare, directly navigating to a non-root route (e.g., /example) results in a React hydration error. The same route works correctly when accessed via client-side navigation (e.g., clicking a <Link> from /).

On direct navigation to a non-root route, React throws a hydration mismatch error and the page visibly flashes:

Hydration failed because the server rendered HTML didn't match the client. 
As a result this tree will be regenerated on the client.

Error reference: https://react.dev/errors/418?args[]=HTML&args[]=

This issue appears to be directly related to Cloudflare's SPA handling configuration:

"not_found_handling": "single-page-application"
Your Example Website or App

https://github.com/bbertold/tanstack-start-spa

Steps to Reproduce the Bug or Issue
  1. Clone the reproduction repository
  2. Build the application: pnpm build
  3. Preview the build: pnpm preview
  4. Open browser and navigate directly to /example in the URL bar
  5. Press Enter
  6. Observe the hydration error in console and visible flash of content
Expected behavior

The page should load without hydration errors.

Screenshots or Videos

No response

Platform
  • Router / Start Version: 1.154.8
  • OS: macOS
  • Browser: Chrome (144.0.7559.59)
  • Bundler: Vite (7.1.7)
  • Wrangler version: 4.60.0
Additional context

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked reproduction repository and run pnpm build followed by pnpm preview; compare direct navigation to /example with client-side navigation. Inspect the Cloudflare SPA configuration, especially "not_found_handling": "single-page-application", and the TanStack Start hydration path. Done means direct navigation loads without a hydration error or visible flash.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript, vite
Domain
cloud, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.