ErrorBoundary causes hydration mismatch and style flicker on non-existent routes #10734

DanielRamosAcosta · 2025-07-25T05:40:11Z

DanielRamosAcosta
Jul 25, 2025

Reproduction

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.5

Used 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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

ErrorBoundary causes hydration mismatch and style flicker on non-existent routes #10734

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

ErrorBoundary causes hydration mismatch and style flicker on non-existent routes #10734

Uh oh!

Uh oh!

DanielRamosAcosta Jul 25, 2025

Reproduction

System Info

Used Package Manager

Expected Behavior

Actual Behavior

Replies: 0 comments

DanielRamosAcosta
Jul 25, 2025