"Cannot call replaceState(...) before router is initialized" in $effect

[al3xnag]

Describe the bug

It's a bit counter-intuitive that router is still not initialized inside $effect, when the router actually has already resolved the route and rendered the page and components.

// src/routes/+page.svelte
<script>
  import { replaceState } from '$app/navigation';

  $effect(() => {
    replaceState('#asd', {});
  });
</script>

Uncaught (in promise) Error: Cannot call replaceState(...) before router is initialized
  in $effect
  in +page.svelte
  in +layout.svelte
  in root.svelte
  in undefined

Reproduction

https://stackblitz.com/edit/sveltejs-kit-template-default-ygy3pbd3?file=src%2Froutes%2F%2Bpage.svelte

Logs

System Info

System:
    OS: macOS 26.4.1
    CPU: (12) arm64 Apple M3 Pro
    Memory: 136.81 MB / 18.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 22.14.0
    Yarn: 1.22.22
    npm: 10.9.2
  Browsers:
    Chrome: 148.0.7778.216
    Firefox: 151.0.2
    Safari: 26.4
  npmPackages:
    @sveltejs/adapter-auto: ^7.0.1 => 7.0.1
    @sveltejs/adapter-static: ^3.0.10 => 3.0.10
    @sveltejs/kit: ^2.57.0 => 2.61.1
    @sveltejs/vite-plugin-svelte: ^7.0.0 => 7.1.2
    svelte: ^5.55.2 => 5.55.9
    vite: ^8.0.7 => 8.0.14

Severity

annoyance

Additional Information

No response

[Nic-Polumeyv]

Reproduces on current main. It's DEV-only: the guard in pushState/replaceState sits inside if (DEV) (client.js:2450 / :2497), so a production build lets the call through.

The cause is a timing gap. started is set at the end of initialize() (client.js:727), but the root component mounts earlier in the same function (client.js:687), so a top-level $effect runs while started is still false even though the route has resolved and the page is rendered. Deferring out of the initial render (e.g. wrapping the call in setTimeout) avoids it, since started is true by then.

Possible directions:

1. Set started = true before the initial effects run. Simplest, but started also gates first-navigation/hydration logic (e.g. client.js:1712, :2248), so it risks the boot path.
2. Guard on a separate "initial render done" flag instead of started, so shallow routing is allowed once the page has rendered.
3. Keep the behavior but make the error/docs clearer that these can't be called synchronously during initial render.

Happy to open a PR for whichever you'd prefer. Is there a reason started needs to be set this late, or would (1) be acceptable?

[roderickdecorrespondent]

+1, we're running into this issue as well

[Nic-Polumeyv]

I found this and it reminded me: #11466 was closed on the logic that Svelte 5 runs onMount after a tick, but $effect still fires before started flips, so the gap is reachable either way. I've hit this multiple times in my own apps, so I'll open a PR for option 2.

[Nic-Polumeyv]

Well, I just learned something new, it's worse than a dev annoyance. In production the guard doesn't exist and the same call crashes with TypeError: Cannot read properties of undefined (reading '$set'), because effects flush while the root component is still being created, before root is assigned. Working on it still.