ErrorBoundary causes hydration mismatch and style flicker on non-existent routes #10697
Description
Reproduction
Link to StackBlitz
I’ve started a new personal project with Remix, and I've added error handling following the Error Handling documentation.
I created a custom ErrorBoundary component as described. But when I navigate to a non-existent route (e.g., /not-exists), the page briefly renders with the correct styles, then re-renders without them.
Console output:
Warning: Expected server HTML to contain a matching <html> in <body>. Error Component Stack
at html (<anonymous>)
at ErrorBoundary (root.tsx:49:17)
at body (<anonymous>)
at html (<anonymous>)
at Layout (root.tsx:26:26)
chunk-674SED4H.js?v=556718a5:9518 Uncaught Error: Hydration failed because the initial UI does not match what was rendered on the server.
at throwOnHydrationMismatch (chunk-674SED4H.js?v=556718a5:9518:17)
at tryToClaimNextHydratableInstance (chunk-674SED4H.js?v=556718a5:9539:15)
at updateHostComponent (chunk-674SED4H.js?v=556718a5:14840:13)
at beginWork (chunk-674SED4H.js?v=556718a5:15981:22)
at HTMLUnknownElement.callCallback2 (chunk-674SED4H.js?v=556718a5:3678:22)
at Object.invokeGuardedCallbackDev (chunk-674SED4H.js?v=556718a5:3703:24)
at invokeGuardedCallback (chunk-674SED4H.js?v=556718a5:3737:39)
at beginWork$1 (chunk-674SED4H.js?v=556718a5:19816:15)
at performUnitOfWork (chunk-674SED4H.js?v=556718a5:19249:20)
at workLoopConcurrent (chunk-674SED4H.js?v=556718a5:19240:13)
hook.js:608 Warning: An error occurred during hydration. The server HTML was replaced with client content in <#document>.
What’s strange is that this is a completely new project, set up exactly as described in the official documentation for error handling.
I’m not sure whether this is a Remix bug or an issue with the documentation itself.
System Info
System:
OS: macOS 15.5
CPU: (10) arm64 Apple M2 Pro
Memory: 87.69 MB / 16.00 GB
Shell: 4.0.2 - /opt/homebrew/bin/fish
Binaries:
Node: 24.2.0 - ~/.local/state/fnm_multishells/21258_1753421962954/bin/node
Yarn: 1.22.22 - ~/.local/state/fnm_multishells/21258_1753421962954/bin/yarn
npm: 11.3.0 - ~/.local/state/fnm_multishells/21258_1753421962954/bin/npm
pnpm: 8.10.5 - ~/.local/state/fnm_multishells/21258_1753421962954/bin/pnpm
bun: 1.2.9 - ~/.bun/bin/bun
Browsers:
Chrome: 138.0.7204.169
Safari: 18.5
npmPackages:
@remix-run/dev: ^2.16.8 => 2.16.8
@remix-run/node: ^2.16.8 => 2.16.8
@remix-run/react: ^2.16.8 => 2.16.8
@remix-run/serve: ^2.16.8 => 2.16.8
vite: ^6.0.0 => 6.3.5Used Package Manager
npm
Expected Behavior
The ErrorBoundary page should render correctly without losing styles, and hydration should complete without errors or warnings.
Actual Behavior
- The page initially renders with the correct styles, then re-renders without them.
- Console shows warnings and errors related to server/client HTML mismatch and hydration failure.