SvelteKit hydration mismatch failure in CI

By Kaveh Alemi·Latchkey

SvelteKit reuses the server-rendered HTML when it hydrates on the client. If the client produces different markup (from random values, dates, or browser-only branches), hydration mismatches, the console warns, and end-to-end tests that assert on the DOM fail.

What this error means

An end-to-end test fails because the hydrated DOM differs from the server HTML, with a console warning about hydration, or interactive elements not responding after load.

[svelte] Hydration failed because the initial UI does not match what was
rendered on the server. Expected <span>10:00</span> but got <span>10:03</span>

Common causes

Non-deterministic values between server and client

Rendering Date.now(), Math.random(), or a locale-dependent format produces different output on the server than on the client, so hydration mismatches.

Branching on a browser-only condition during render

Rendering different markup based on window or feature detection makes the client tree diverge from the server tree.

How to fix it

Make render output deterministic

1. Identify the element that differs between server and client.
2. Compute time, random, or locale values after mount, not during render.
3. Re-run the end-to-end test.

import { onMount } from 'svelte';
let now = '';
onMount(() => { now = new Date().toLocaleTimeString(); });

Keep render output identical on both sides

Avoid branching markup on browser-only conditions during render; defer browser-specific UI to after hydration.

How to prevent it

• Compute time/random/locale values after mount, not during render.
• Do not branch render output on window or feature detection.
• Run end-to-end tests against the built app to catch hydration drift.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation