sveltejs/kit · warning

`replaceState(...)` is deprecated. Use `goto(url, { state, s

Error message

`replaceState(...)` is deprecated. Use `goto(url, { state, shallow: true, replace: true })` instead.

What it means

SvelteKit's client runtime emits this DEV-only console warning when the exported `replaceState(url, state)` function is called. It is superseded by `goto(url, { state, shallow: true, replace: true })`, which replaces the current history entry instead of pushing a new one. The call still works; this is purely a migration warning.

Source

Thrown at packages/kit/src/runtime/client/client.js:2942

		intent,
		state,
		{ replace: false, persist_state: false, reset: false },
		'pushState'
	);
}

/**
 * Programmatically replace the current history entry with the given `page.state`. Used for [shallow routing](https://svelte.dev/docs/kit/shallow-routing).
 *
 * @deprecated Use `goto(url, { state, shallow: true, replace: true })` instead.
 * @param {string | URL} url
 * @param {App.PageState} state
 * @returns {Promise<void>}
 */
export async function replaceState(url, state) {
	if (DEV && !warned_on_replace_state_function) {
		warned_on_replace_state_function = true;
		console.warn(
			'`replaceState(...)` is deprecated. Use `goto(url, { state, shallow: true, replace: true })` instead.'
		);
	}

	const intent = await resolve_intent(url, 'replaceState');

	await update_state(
		intent,
		state,
		{ replace: true, persist_state: false, reset: false },
		'replaceState'
	);
}

/**
 * @param {NavigationIntent} intent
 * @param {App.PageState} state
 * @param {{ replace: boolean; persist_state: boolean; reset: boolean; }} options

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Replace `replaceState(url, state)` with `goto(url, { state, shallow: true, replace: true })`
2. Confirm behavior is identical (history entry replaced, `page.state` updated)
3. Remove leftover pushState/replaceState imports

Example fix

// before
import { replaceState } from '$app/navigation';
replaceState('?page=2', { page: 2 });
// after
import { goto } from '$app/navigation';
goto('?page=2', { state: { page: 2 }, shallow: true, replace: true });

if (DEV && /replaceState\s*\(/.test(source)) console.warn('replace replaceState with goto replace:true');

const usesReplaceState = (src) => /\breplaceState\s*\(/.test(src);

When it happens

Trigger: Calling `replaceState(url, state)` from `@sveltejs/kit` in client code (e.g. syncing URL to form/filter state) during development, first use per page load.

Common situations: Older codebases using replaceState to keep URL/state in sync without creating history entries (search inputs, wizard steps) after upgrading SvelteKit.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• `pushState(...)` is deprecated. Use `goto(url, { state, shal
• Reading `config.kit` inside adapters is deprecated — it shou
• The `${keypath}` option is deprecated, and will be removed i
• `$app/environment` is deprecated, use `$app/env` instead
• `data-sveltekit-${name}="true"` has been replaced with `data

AI-assisted analysis of sveltejs/kit@03f1687fe6 (2026-09-02). Data as JSON: /api/errors/76787266506276b5. Report an issue: GitHub.