sveltejs/svelte · error · Error

hydratable_missing_but_required

hydratable_missing_but_required

Error message

hydratable_missing_but_required
Expected to find a hydratable with key `${key}` during hydration, but did not.
https://svelte.dev/e/hydratable_missing_but_required

What it means

Thrown at internal/client/hydratable.js:26 during hydration when a hydratable(key, fn) call cannot find `key` in the server-provided data store (window.__svelte.h). In DEV this is a hard error because a missing required hydratable means the server and client disagree on what should be serialised; in production it downgrades to a warning.

Source

Thrown at packages/svelte/src/internal/client/errors.js:328

	} else {
		throw new Error(`https://svelte.dev/e/get_abort_signal_outside_reaction`);
	}
}

/**
 * Expected to find a hydratable with key `%key%` during hydration, but did not.
 * @param {string} key
 * @returns {never}
 */
export function hydratable_missing_but_required(key) {
	if (DEV) {
		const error = new Error(`hydratable_missing_but_required\nExpected to find a hydratable with key \`${key}\` during hydration, but did not.\nhttps://svelte.dev/e/hydratable_missing_but_required`);

		error.name = 'Svelte error';

		throw error;
	} else {
		throw new Error(`https://svelte.dev/e/hydratable_missing_but_required`);
	}
}

/**
 * Failed to hydrate the application
 * @returns {never}
 */
export function hydration_failed() {
	if (DEV) {
		const error = new Error(`hydration_failed\nFailed to hydrate the application\nhttps://svelte.dev/e/hydration_failed`);

		error.name = 'Svelte error';

		throw error;
	} else {
		throw new Error(`https://svelte.dev/e/hydration_failed`);
	}
}

View on GitHub (pinned to 20b341f100)

Solutions

1. Ensure the server-side render path produces the same hydratable keys the client consumes — check conditional logic is identical on both sides.
2. Verify the key string matches exactly between the hydratable() call and the server serialisation.
3. If the data is optional, handle its absence in fn() rather than requiring it, or guard the hydratable call.
4. Reproduce in DEV to get the exact missing key, then trace it on the server.

Example fix

// before — client requires a key the server never set
const data = hydratable('user-prefs', () => fetchPrefs());
// server never wrote 'user-prefs'

// after — align server and client
// server: provide the data under the same key
// client: keep key consistent
const data = hydratable('user-prefs', () => fetchPrefs());

// Ensure server and client agree on hydratable keys.
// In DEV, wrap hydratable usage to surface the key early:
// if (import.meta.env.DEV) console.assert(serverKeys.has(key), 'missing', key);

When it happens

Trigger: A component uses hydratable() to claim pre-serialised server data, but the server render did not emit that key (different code path, conditional render mismatch, or the data was never set). hydrating is true and store.has(key) is false.

Common situations: SSR and client use different component versions; conditional rendering means the server skipped a subtree but the client tries to hydrate it; key typo between server write and client read; async streaming boundaries where data wasn't flushed; enabling hydratable on an existing component without updating the server.

Related errors

• fork_discarded
• fork_timing
• hydration_failed
• get_abort_signal_outside_reaction
• set_context_after_init

AI-assisted analysis of sveltejs/svelte@20b341f100 (2026-08-12). Data as JSON: /api/errors/76da741c48e13792. Report an issue: GitHub.