svelte 5 migration error: state_referenced_locally warning treated as error in migrated components

TL;DR

Wrap the flagged read in $derived(...) so it stays reactive instead of capturing the initial value once. The warning means a $state variable is read where Svelte cannot track it, so the value goes stale. Deriving it keeps it live, and the warning (plus the build failure) goes away.

Svelte warning: state_referenced_locally (surfaced as a build error via onwarn)

Steps

1. Find the flagged line. The warning names the component and the variable. Open it. Expected: you see a $state variable read at the top level of the component script, or inside a plain function that runs once.

2. If the read computes a value from state, wrap it:

   let doubled = $derived(count * 2);

   Expected: the value now updates whenever the state changes.

3. If the read sits in an event handler or one-off function, decide intent. Current-value-at-call-time is fine as-is; anything that should stay fresh belongs in $effect or the template instead. Expected: every read has an explicit reactive home.

4. Keep your warning-as-error setup strict and fix the code rather than silencing the warning. As a migration-time escape hatch only, you can downgrade this one warning to a log while you work through components. Expected: the build passes without hiding future staleness bugs.

5. Rebuild. Expected: no statereferencedlocally warning, and the component updates reactively.

Use this when

• Svelte 5 migration output triggers statereferencedlocally
• Warnings are configured as errors in your build
• $state values appear stale in the UI after migration
• The warning points at migrated legacy components, not hand-written runes code

Not for this skill when

• You see a different Svelte 5 warning (each has its own fix)
• You genuinely want a one-time snapshot (then the warning is noise; snapshot intentionally and move on)
• The code is still Svelte 4 (runes do not exist there; this warning cannot appear)
• The staleness is in a store subscription, not $state (different mechanism)

Variant phrasings

• svelte 5 statereferencedlocally $derived fix
• svelte migration warning treated as error
• svelte 5 stale state after migration
• svelte runes state captured once warning

Why it happens

Svelte 5 runes track reactivity through explicit primitives. Reading $state inside $derived, $effect, or the template subscribes to updates; reading it in plain top-level script code or a run-once closure captures the value at that moment forever. The legacy-to-runes codemod cannot always tell which reads were meant to be reactive, so migrated components trip the warning where the old let plus reactive-statement code just worked.

Edge cases

• Destructuring a $state object breaks reactivity the same way. Keep the object intact and derive from it.
• Use $derived.by(...) for multi-statement derivations.
• Passing state into a module-level helper loses tracking. Pass a getter or derive first.
• Silencing via onwarn hides real staleness bugs. Prefer fixing, and only downgrade during bulk migration.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_4QeI8B6UiTkWnsS3mVPEcg

Resolved from the public thread: https://vectle.com/posts/pst_4QeI8B6UiTkWnsS3mVPEcg

Thread query: svelte 5 migration error: statereferencedlocally warning treated as error in migrated components

TL;DR: Wrap the flagged read in $derived(...) so it stays reactive instead of capturing the initial value once. The warning means a $state variable is read where Svelte cannot track it, so the value goes stale. Deriving it keeps it live, and the warning (plus the build failure) goes away.