## Pages ### client-errors Complete reference of Svelte runtime errors with causes and solutions: reactivity constraints ($derived/$effect rules), binding restrictions, component API changes, state mutation rules, async/fork limitations, and boundary error handling. ## Client-side Error Reference Comprehensive list of runtime errors that can occur in Svelte applications with explanations and solutions. ### Reactivity Errors **async_derived_orphan**: Cannot create `$derived(...)` with `await` outside effect tree. Deriveds run lazily and can be garbage collected, but async deriveds need effects to call promises proactively. Solution: create async deriveds inside effects. **derived_references_self**: A derived cannot reference itself recursively. **effect_in_unowned_derived**: Effects cannot be created inside `$derived` values that weren't themselves created inside an effect. **effect_orphan**: `$rune%` can only be used inside effects or during component initialization. **effect_in_teardown**: `%rune%` cannot be used inside effect cleanup functions. **effect_pending_outside_reaction**: `$effect.pending()` can only be called inside effects or deriveds. **effect_update_depth_exceeded**: Maximum update depth exceeded, typically when an effect reads and writes the same state. Example causing infinite loop: ```js let count = $state(0); $effect(() => { count += 1; // reads and writes count }); ``` Same issue with array mutations: ```js let array = $state(['hello']); $effect(() => { array.push('goodbye'); // reads and writes array }); ``` Solution: use `untrack()` to read state without adding dependency, or make non-state values (like logs arrays) regular variables instead of `$state()`. **state_unsafe_mutation**: Updating state inside `$derived(...)`, `$inspect(...)` or template expressions is forbidden. Example: ```svelte ``` Solution: make everything derived: ```js let count = 0; let even = $derived(count % 2 === 0); let odd = $derived(!even); ``` Or use `$effect` for side-effects. ### Binding Errors **bind_invalid_checkbox_value**: Using `bind:value` with checkbox input is not allowed. Use `bind:checked` instead. **bind_invalid_export**: Component has export that consumer tries to access via `bind:%key%`, which is disallowed. Solution: use `bind:this` to bind component instance, then access property on it. **bind_not_bindable**: Attempting to bind to non-bindable property. Solution: mark property as bindable with `let { %key% = $bindable() } = $props()`. **props_invalid_value**: Cannot do `bind:%key%={undefined}` when `%key%` has a fallback value. **props_rest_readonly**: Rest element properties of `$props()` are readonly. ### Component Errors **component_api_changed**: Calling `%method%` on component instance is no longer valid in Svelte 5. **component_api_invalid_new**: Attempted to instantiate component with `new %name%`, no longer valid in Svelte 5. Solution: set `compatibility.componentApi` compiler option to `4` to keep working. ### Loop Errors **each_key_duplicate**: Keyed each block has duplicate key at indexes or with value `%value%` at indexes. ### Context & Lifecycle Errors **set_context_after_init**: `setContext` must be called during component initialization, not in subsequent effects or after `await`. (Applies with `experimental.async` option, default in Svelte 6) **lifecycle_legacy_only**: `%name%(...)` cannot be used in runes mode. ### State Errors **state_descriptors_fixed**: Property descriptors on `$state` objects must contain `value` and be `enumerable`, `configurable`, and `writable`. **state_prototype_fixed**: Cannot set prototype of `$state` object. ### Async/Fork Errors **experimental_async_fork**: Cannot use `fork(...)` unless `experimental.async` compiler option is `true`. **fork_discarded**: Cannot commit fork that was already discarded. **fork_timing**: Cannot create fork inside effect or when state changes are pending. **flush_sync_in_effect**: Cannot use `flushSync` inside effect. Can call after state change but not during effect flushing. (Applies with `experimental.async` option) ### Other Errors **get_abort_signal_outside_reaction**: `getAbortSignal()` can only be called inside effects or deriveds. **hydration_failed**: Failed to hydrate the application. **invalid_snippet**: Could not `{@render}` snippet because expression is `null` or `undefined`. Solution: use optional chaining `{@render snippet?.()}`. **rune_outside_svelte**: `%rune%` rune only available inside `.svelte` and `.svelte.js/ts` files. **svelte_boundary_reset_onerror**: `` `reset` function cannot be called while error is being handled. Solution: wait for boundary to settle before calling `reset()`, e.g. with `await tick()`: ```svelte { fixTheError(); await tick(); reset(); }> ``` ### client-warnings 18 client-side warnings covering state mutations, reactivity tracking, hydration mismatches, component ownership, and lifecycle issues with fixes for each. Reference documentation for Svelte client-side warnings. Each warning explains a potential issue and how to fix it. **assignment_value_stale**: Assignment operators like `??=` evaluate to the right-hand side value, not the final state value. This can cause unexpected behavior when chaining operations. Fix by separating into two statements: ```js object.array ??= []; object.array.push(object.array.length); ``` **await_reactivity_loss**: State read in async functions after an `await` may not be tracked for reactivity. Pass values as function parameters instead of reading them inside the async function: ```js async function sum(a, b) { return await a + b; } let total = $derived(await sum(a, b)); ``` **await_waterfall**: Multiple `$derived(await ...)` expressions create unnecessary waterfalls where the second waits for the first to resolve. Create promises first, then await them: ```js let aPromise = $derived(one()); let bPromise = $derived(two()); let a = $derived(await aPromise); let b = $derived(await bPromise); ``` **binding_property_non_reactive**: Binding to a non-reactive property. **console_log_state**: Logging `$state` proxies shows the proxy object, not the value. Use `$inspect(...)` or `$state.snapshot(...)` instead. **event_handler_invalid**: Event handler is not a function. **hydration_attribute_changed**: Certain attributes like `src` on `` won't update during hydration. Ensure values match between server and client, or force an update in an `$effect`: ```svelte ``` **hydration_html_changed**: `{@html ...}` values that differ between server and client won't update during hydration. Use the same pattern as hydration_attribute_changed. **hydration_mismatch**: Server-rendered HTML structure doesn't match client expectations. Usually caused by invalid HTML that the DOM repairs. **invalid_raw_snippet_render**: `createRawSnippet` render function must return HTML for a single element. **legacy_recursive_reactive_block**: Migrated `$:` reactive blocks that both read and update the same value may cause recursive updates when converted to `$effect`. **lifecycle_double_unmount**: Attempted to unmount a component that wasn't mounted. **ownership_invalid_binding**: Parent component didn't declare a binding that child is trying to bind to. Use `bind:` in parent instead of just passing the property: ```svelte ``` **ownership_invalid_mutation**: Mutating unbound props is discouraged. Use `bind:` or callbacks instead, or mark the prop as `$bindable`: ```svelte ``` **select_multiple_invalid_value**: ` {/each} ``` In runes mode, use index: ```svelte {#each array as entry, i} {/each} ``` - `each_key_without_as`: `{#each}` without `as` clause cannot have key ### Effect/Element Errors - `effect_invalid_placement`: `$effect()` only as expression statement - `element_invalid_closing_tag`: Closing tag for unopened element - `element_invalid_closing_tag_autoclosed`: Closing tag for auto-closed element (nesting violation) - `element_unclosed`: Element left open ### Event Handler Errors - `event_handler_invalid_component_modifier`: Only `once` modifier on components; others only on DOM elements - `event_handler_invalid_modifier`: Invalid event modifier - `event_handler_invalid_modifier_combination`: Incompatible modifier combination ### Expected/Experimental Errors - `expected_attribute_value`: Expected attribute value - `expected_block_type`: Expected `if`, `each`, `await`, `key`, or `snippet` - `expected_identifier`: Expected identifier - `expected_pattern`: Expected identifier or destructure pattern - `expected_token`: Expected specific token - `expected_whitespace`: Expected whitespace - `experimental_async`: Cannot use `await` in deriveds/template expressions/top-level unless `experimental.async` compiler option is true ### Export/Global Errors - `export_undefined`: Variable not defined - `global_reference_invalid`: Illegal variable name; use `globalThis.%name%` for globals ### Host/Illegal Errors - `host_invalid_placement`: `$host()` only in custom element component instances - `illegal_element_attribute`: Element doesn't support non-event/spread attributes ### Import/Inspect Errors - `import_svelte_internal_forbidden`: Cannot import from `svelte/internal/*` (private, subject to change) - `inspect_trace_generator`: `$inspect.trace()` cannot be in generator function - `inspect_trace_invalid_placement`: `$inspect.trace()` must be first statement in function body ### Invalid/JS Parse Errors - `invalid_arguments_usage`: `arguments` keyword not in template or top-level component - `js_parse_error`: JavaScript parse error ### Legacy Errors - `legacy_await_invalid`: Cannot use `await` in deriveds/template expressions/top-level unless in runes mode - `legacy_export_invalid`: Cannot use `export let` in runes mode; use `$props()` instead - `legacy_props_invalid`: Cannot use `$$props` in runes mode - `legacy_reactive_statement_invalid`: `$:` not allowed in runes mode; use `$derived` or `$effect` - `legacy_rest_props_invalid`: Cannot use `$$restProps` in runes mode ### Let/Mixed/Module Errors - `let_directive_invalid_placement`: `let:` directive at invalid position - `mixed_event_handler_syntaxes`: Cannot mix `on:%name%` and `on%name%` syntaxes - `module_illegal_default_export`: Component cannot have default export ### Node/Options Errors - `node_invalid_placement`: Element placement violates HTML restrictions; browser will repair HTML breaking Svelte assumptions Examples: - `

hello

world

` → `

hello

world

` (div closes p) - `` → `` (div removed) - `

cell

` → `

cell

` (tbody inserted) - `options_invalid_value`: Invalid compiler option - `options_removed`: Removed compiler option - `options_unrecognised`: Unrecognized compiler option ### Props Errors - `props_duplicate`: Cannot use `%rune%()` more than once - `props_id_invalid_placement`: `$props.id()` only at top level as variable declaration initializer - `props_illegal_name`: Cannot declare/access prop starting with `$$` (reserved) - `props_invalid_identifier`: `$props()` only with object destructuring pattern - `props_invalid_pattern`: `$props()` cannot contain nested properties or computed keys - `props_invalid_placement`: `$props()` only at top level as variable declaration initializer ### Reactive/Render Errors - `reactive_declaration_cycle`: Cyclical dependency in reactive declaration - `render_tag_invalid_call_expression`: Cannot call snippet using apply/bind/call - `render_tag_invalid_expression`: `{@render}` only contains call expressions - `render_tag_invalid_spread_argument`: Cannot use spread in `{@render}` tags ### Rune Errors - `rune_invalid_arguments`: Rune cannot be called with arguments - `rune_invalid_arguments_length`: Rune must be called with specific number of arguments - `rune_invalid_computed_property`: Cannot access computed property of rune - `rune_invalid_name`: Not a valid rune - `rune_invalid_spread`: Rune cannot be called with spread argument - `rune_invalid_usage`: Cannot use rune in non-runes mode - `rune_missing_parentheses`: Cannot use rune without parentheses - `rune_removed`: Rune has been removed - `rune_renamed`: Rune renamed to different name ### Runes Mode/Script Errors - `runes_mode_invalid_import`: Cannot use in runes mode - `script_duplicate`: Component can have single ` {#snippet greeting(name)}

{message} {name}!

{/snippet} ``` - `snippet_invalid_rest_parameter`: Snippets don't support rest parameters; use array - `snippet_parameter_assignment`: Cannot reassign/bind to snippet parameter - `snippet_shadowing_prop`: Snippet shadows prop with same name ### State Errors - `state_field_duplicate`: State field already declared on class Example: ```js class Counter { count = $state(0); // declaration in class body } // or in constructor: class Counter { constructor() { this.count = $state(0); // only happens once } } ``` - `state_field_invalid_assignment`: Cannot assign to state field before declaration - `state_invalid_export`: Cannot export state from module if reassigned; export function or only mutate properties - `state_invalid_placement`: `%rune%()` only as variable declaration initializer, class field declaration, or first assignment in constructor ### Store Errors - `store_invalid_scoped_subscription`: Cannot subscribe to stores not declared at top level - `store_invalid_subscription`: Cannot reference store value in `

{stale}

``` **options_deprecated_accessors**: `accessors` option deprecated in runes mode. **options_deprecated_immutable**: `immutable` option deprecated in runes mode. **options_missing_custom_element**: Using custom element features without `customElement: true` option. **options_removed_enable_sourcemap**: `enableSourcemap` removed - source maps always generated. **options_removed_hydratable**: `hydratable` removed - components always hydratable. **options_removed_loop_guard_timeout**: `loopGuardTimeout` removed. **options_renamed_ssr_dom**: `generate: "dom"` → `"client"`, `generate: "ssr"` → `"server"`. **perf_avoid_inline_class**: Declare classes at top level, not inline. **perf_avoid_nested_class**: Don't declare classes in nested scopes. **reactive_declaration_invalid_placement**: Reactive declarations only at top level of instance script. **reactive_declaration_module_script_dependency**: Module-level reassignments don't trigger reactive statements. **script_context_deprecated**: Use `module` attribute instead of `context="module"`. ```svelte ``` **script_unknown_attribute**: Only `generics`, `lang`, `module` allowed on `

{count()}

``` **store_rune_conflict**: Local binding conflicts with `$%name%` store rune. Rename to avoid ambiguity. **svelte_component_deprecated**: `` deprecated - components dynamic by default. Use `{@const Component = ...}` or derived values. ```svelte {@const Component = condition ? Y : Z} ``` **svelte_element_invalid_this**: `` should use expression, not string. **svelte_self_deprecated**: Use self-imports instead of ``. **unknown_code**: Unrecognized warning code (possibly typo). ### server-errors Server-side rendering errors: await in sync render, deprecated html property, unavailable lifecycle methods. ## Server-side rendering errors ### await_invalid Encountered asynchronous work while rendering synchronously. When calling `render(...)` with a component containing an `await` expression, either await the result of `render` or wrap the `await` (or the component containing it) in a `` with a `pending` snippet. ### html_deprecated The `html` property of server render results has been deprecated. Use `body` instead. ### lifecycle_function_unavailable `%name%(...)` is not available on the server. Certain methods such as `mount` cannot be invoked while running in a server context. Avoid calling them eagerly, i.e. not during render. ### shared-errors Common Svelte runtime errors: snippet/render misuse, lifecycle method placement, context setup, store shape, and element binding constraints. ## Error Reference ### invalid_default_snippet Cannot use `{@render children(...)}` if parent uses `let:` directives. Use named snippets instead. ```svelte // Parent.svelte - WRONG {entry} // List.svelte

{@render children(item)}

``` The `let:` directive and `{@render children()}` are incompatible APIs. ### invalid_snippet_arguments A snippet function was passed invalid arguments. Snippets should only be instantiated via `{@render ...}`. ### lifecycle_outside_component `%name%(...)` can only be used during component initialisation. Must be invoked at the top level of the instance script. ```svelte ``` ### missing_context Context was not set in a parent component. The `createContext()` utility returns `[get, set]` pair; `get` throws if `set` wasn't called in a parent. ### snippet_without_render_tag Attempted to render a snippet without `{@render}` block, causing stringification instead of DOM rendering. ```svelte // WRONG - children not rendered {children} // WRONG - parent passes snippet where non-snippet expected // Parent.svelte {#snippet label()} Hi! {/snippet} // Child.svelte

{label}

// CORRECT

{@render label()}

``` ### store_invalid_shape `%name%` is not a store with a `subscribe` method. ### svelte_element_invalid_this_value The `this` prop on `` must be a string, if defined. ### shared-warnings Two shared warnings: void elements ignore children; $state.snapshot() returns originals for uncloneable values like DOM elements. ## dynamic_void_element_content Void elements like `` cannot have content. When using `` with a void element tag, any children passed will be ignored. ## state_snapshot_uncloneable `$state.snapshot()` attempts to clone a value to return a reference that no longer changes. Some objects cannot be cloned and the original value is returned instead. Example: ```js const object = $state({ property: 'this is cloneable', window }) const snapshot = $state.snapshot(object); // property is cloned, but window (DOM element) is not cloneable ``` Properties that cannot be cloned are listed in the warning message.

Error & Warning Reference