{"record":{"id":"3f644a53a95f669e","repo":"sveltejs/svelte","slug":"hydration-failed","errorCode":"hydration_failed","errorMessage":"hydration_failed\nFailed to hydrate the application\nhttps://svelte.dev/e/hydration_failed","messagePattern":"hydration_failed\nFailed to hydrate the application\nhttps://svelte\\.dev/e/hydration_failed","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/svelte/src/internal/client/errors.js","lineNumber":344,"sourceCode":"\t\tthrow error;\n\t} else {\n\t\tthrow new Error(`https://svelte.dev/e/hydratable_missing_but_required`);\n\t}\n}\n\n/**\n * Failed to hydrate the application\n * @returns {never}\n */\nexport function hydration_failed() {\n\tif (DEV) {\n\t\tconst error = new Error(`hydration_failed\\nFailed to hydrate the application\\nhttps://svelte.dev/e/hydration_failed`);\n\n\t\terror.name = 'Svelte error';\n\n\t\tthrow error;\n\t} else {\n\t\tthrow new Error(`https://svelte.dev/e/hydration_failed`);\n\t}\n}\n\n/**\n * Could not `{@render}` snippet due to the expression being `null` or `undefined`. Consider using optional chaining `{@render snippet?.()}`\n * @returns {never}\n */\nexport function invalid_snippet() {\n\tif (DEV) {\n\t\tconst error = new Error(`invalid_snippet\\nCould not \\`{@render}\\` snippet due to the expression being \\`null\\` or \\`undefined\\`. Consider using optional chaining \\`{@render snippet?.()}\\`\\nhttps://svelte.dev/e/invalid_snippet`);\n\n\t\terror.name = 'Svelte error';\n\n\t\tthrow error;\n\t} else {\n\t\tthrow new Error(`https://svelte.dev/e/invalid_snippet`);\n\t}\n}","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/sveltejs/svelte/blob/20b341f10048cf1016a2028ac7eee5595cfef6a5/packages/svelte/src/internal/client/errors.js#L326-L362","documentation":"Thrown at internal/client/render.js:138 when hydration encounters a mismatch and options.recover is false. By default Svelte recovers from hydration mismatches by re-rendering from scratch; with recover:false any mismatch is fatal, surfacing as this error so you are forced to fix the server/client divergence.","triggerScenarios":"Mounting with hydrate: true and recover: false when the server-rendered HTML does not match what the client would produce — different data, time-based output, random values, browser-only APIs called during render, or template differences between server and client builds.","commonSituations":"Date/Math.random output in templates; using window/document during render; cached vs fresh SSR data; mismatched component versions; CSS-only or feature-flag differences; enabling recover:false in tests to catch SSR bugs.","solutions":["Make the offending render output deterministic — move non-deterministic work (dates, randomness, browser APIs) into onMount or an effect so SSR and initial client render agree.","Ensure server and client receive identical initial data for the hydrating component.","Temporarily set recover: true (default) to see the recovered DOM and isolate which node mismatches, then fix the root cause.","Use DEV mode hydration warnings to locate the exact mismatch node."],"exampleFix":"// before — non-deterministic output\n<h1>{new Date().toLocaleTimeString()}</h1>\n// SSR time != client hydration time -> mismatch\n\n// after\n<script>\n  let time = $state('');\n  onMount(() => { time = new Date().toLocaleTimeString(); });\n</script>\n<h1>{time}</h1>","handlingStrategy":"try-catch","validationCode":"// Before enabling recover:false, ensure deterministic render output.\n// Audit templates for: Date.now(), Math.random(), window/document access, time-based formatting.\n// Move non-deterministic work into onMount/$effect so SSR and first client render match.","typeGuard":null,"tryCatchPattern":"// Hydration errors can be caught at the mount call site:\ntry {\n  mount(App, { target, hydrate: true, recover: false });\n} catch (e) {\n  // fall back to non-hydrating mount\n  target.innerHTML = '';\n  mount(App, { target });\n}","preventionTips":["Avoid non-deterministic values (dates, randomness) in component render bodies.","Keep SSR and client initial data identical.","Run the app in DEV mode to see hydration mismatch warnings before enabling recover:false.","Consider recover:true (default) for production resilience once SSR correctness is verified."],"tags":["svelte","hydration","ssr","rendering"],"backgroundTag":null,"analyzedSha":"20b341f10048cf1016a2028ac7eee5595cfef6a5","analyzedAt":"2026-08-12T23:37:30.399Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}