The Error and Warning System provides a centralized mechanism for defining, generating, and emitting developer-facing error and warning messages throughout Svelte. This system maintains error message definitions in Markdown files, automatically generates JavaScript functions for runtime emission, and produces reference documentation for users. The system operates at both compile-time (within the compiler) and runtime (in client, server, and shared contexts).
For information about compiler errors during the compilation phase, see the Compilation Pipeline documentation (page 3). For runtime reactivity errors and effect system issues, see the Reactivity System documentation (page 4.1).
The error and warning system consists of three main components: source message definitions in Markdown, a code generation script that transforms these definitions into executable functions, and runtime emission logic that uses these functions to report issues to developers.
Sources: packages/svelte/scripts/process-messages/index.js1-431 packages/svelte/src/internal/client/errors.js1-10 packages/svelte/src/internal/client/warnings.js1-7
Svelte organizes error and warning messages into eight distinct categories based on where they occur in the framework lifecycle and which environment they target.
| Category | Purpose | Generated File | Example Codes |
|---|---|---|---|
client-errors | Runtime errors in browser environment | src/internal/client/errors.js | async_derived_orphan, bind_invalid_checkbox_value, effect_update_depth_exceeded |
client-warnings | Runtime warnings in browser environment | src/internal/client/warnings.js | console_log_state, hydration_mismatch, ownership_invalid_mutation |
compile-errors | Build-time compilation errors | src/compiler/errors.js | Parser and analyzer errors |
compile-warnings | Build-time compilation warnings | src/compiler/warnings.js | Linting and best practice warnings |
server-errors | SSR runtime errors | src/internal/server/errors.js | Server-specific rendering errors |
server-warnings | SSR runtime warnings | src/internal/server/warnings.js | Server-specific rendering warnings |
shared-errors | Errors common to both client and server | src/internal/shared/errors.js | Cross-environment errors |
shared-warnings | Warnings common to both client and server | src/internal/shared/warnings.js | Cross-environment warnings |
Sources: packages/svelte/scripts/process-messages/index.js399-407 packages/svelte/messages/client-errors/errors.md1-236 packages/svelte/messages/client-warnings/warnings.md1-344
Error and warning messages are defined in Markdown files with a specific structure that enables automatic code generation. Each message consists of a code identifier, message text variants, and optional detailed explanations.
Each message definition follows this pattern:
Example from client-errors:
packages/svelte/messages/client-errors/errors.md68-107
The message effect_update_depth_exceeded has:
effect_update_depth_exceeded"Maximum update depth exceeded. This typically indicates that an effect reads and writes the same piece of state"Sources: packages/svelte/messages/client-errors/errors.md35-107 packages/svelte/scripts/process-messages/index.js39-64
The process-messages script transforms Markdown definitions into executable JavaScript functions. This script runs during the build process and is also available in watch mode for development.
The script is invoked during build and can run in watch mode:
Key processing steps:
Markdown Parsing packages/svelte/scripts/process-messages/index.js33-72:
.md files from messages/ subdirectories/## ([\w]+)\n\n([^]+?)(?=$|\n\n## )/g to extract message sections> )Parameter Extraction packages/svelte/scripts/process-messages/index.js178-190:
%parameter% placeholdersAST Transformation packages/svelte/scripts/process-messages/index.js125-348:
acornzimmerframe visitor patternCODE → actual error code stringMESSAGE → template literal with interpolated parametersPARAMETER → function parameters from extracted varsJSDoc Generation packages/svelte/scripts/process-messages/index.js350-378:
@param tags for each parameterSources: packages/svelte/scripts/process-messages/index.js17-408
The generated JavaScript functions emit errors and warnings differently based on the environment (development vs production) and message type (error vs warning).
Error functions throw JavaScript Error objects with the error code and message. In development mode, errors include full details; in production, only a URL is provided to keep bundle sizes small.
Generated error function structure packages/svelte/src/internal/client/errors.js239-249:
Usage in runtime code:
When the runtime detects a condition that should halt execution, it imports and calls the error function:
Sources: packages/svelte/src/internal/client/errors.js7-21 packages/svelte/src/internal/client/errors.js239-249
Warning functions use console.warn to log issues without halting execution. Development mode includes styled console output with bold error code prefix and normal weight message text.
Generated warning function structure packages/svelte/src/internal/client/warnings.js13-19:
The styling variables are defined at the module level packages/svelte/src/internal/client/warnings.js5-6:
Usage example packages/svelte/src/internal/client/dev/equality.js21-23:
Sources: packages/svelte/src/internal/client/warnings.js1-19 packages/svelte/src/internal/client/dev/equality.js1-23
The system behaves differently in development and production builds to balance developer experience with production performance.
| Aspect | Development (DEV=true) | Production (DEV=false) |
|---|---|---|
| Error Message | Full error code, message, and details | URL only: https://svelte.dev/e/code |
| Error Name | Set to "Svelte error" | Generic "Error" |
| Warning Style | Styled with bold/normal weight | Plain text URL |
| Bundle Size | Larger (includes all message strings) | Minimal (only URLs) |
| Debug Info | Parameter values interpolated into message | No parameter values |
| Performance | Slower (string interpolation) | Faster (minimal overhead) |
The DEV constant is imported from esm-env packages/svelte/src/internal/client/errors.js3:
This allows bundlers to perform dead code elimination in production builds, removing all development-only code paths.
Sources: packages/svelte/src/internal/client/errors.js3-21 packages/svelte/src/internal/client/warnings.js3-19
Some error and warning messages support multiple variants with different parameter counts. The system generates conditional logic to select the appropriate message based on which parameters are provided.
Example: each_key_duplicate has two variants packages/svelte/messages/client-errors/errors.md39-43:
The generated function uses conditional logic packages/svelte/src/internal/client/errors.js136-148:
The processing script validates that overloads add new parameters packages/svelte/scripts/process-messages/index.js240-243:
Sources: packages/svelte/messages/client-errors/errors.md39-43 packages/svelte/src/internal/client/errors.js136-148 packages/svelte/scripts/process-messages/index.js178-260
The system includes specialized error types that detect common developer mistakes and provide actionable guidance.
Errors related to the reactive system and effect lifecycle:
async_derived_orphan - Creating async derived outside effect tree packages/svelte/messages/client-errors/errors.md1-9effect_orphan - Using effects outside component initialization packages/svelte/messages/client-errors/errors.md59-61effect_update_depth_exceeded - Infinite effect loop detection packages/svelte/messages/client-errors/errors.md67-107derived_references_self - Recursive derived value detection packages/svelte/messages/client-errors/errors.md35-37Errors related to component property binding:
bind_invalid_checkbox_value - Using bind:value on checkbox packages/svelte/messages/client-errors/errors.md11-13bind_not_bindable - Binding to non-$bindable() property packages/svelte/messages/client-errors/errors.md19-21bind_invalid_export - Attempting to bind to exported property packages/svelte/messages/client-errors/errors.md15-27Errors related to SSR hydration mismatch:
hydration_failed - General hydration failure packages/svelte/messages/client-errors/errors.md146-148hydratable_missing_but_required - Missing hydratable during hydration packages/svelte/messages/client-errors/errors.md129-144Errors related to $state and mutations:
state_unsafe_mutation - Mutating state inside $derived packages/svelte/messages/client-errors/errors.md184-217state_descriptors_fixed - Invalid property descriptors on state objects packages/svelte/messages/client-errors/errors.md176-178state_prototype_fixed - Attempting to change state object prototype packages/svelte/messages/client-errors/errors.md180-182Sources: packages/svelte/messages/client-errors/errors.md1-236
Warnings alert developers to potential issues without halting execution.
Warnings that indicate potential performance issues:
await_waterfall - Unnecessary sequential async operations packages/svelte/messages/client-warnings/warnings.md78-107await_reactivity_loss - State read after await loses reactivity packages/svelte/messages/client-warnings/warnings.md33-76Warnings about improper state usage:
console_log_state - Logging $state proxies directly packages/svelte/messages/client-warnings/warnings.md115-121state_proxy_equality_mismatch - Comparing proxies with === or == packages/svelte/messages/client-warnings/warnings.md275-290assignment_value_stale - Assignment evaluation issues with state packages/svelte/messages/client-warnings/warnings.md1-31Warnings about component property ownership:
ownership_invalid_mutation - Mutating props without bind: packages/svelte/messages/client-warnings/warnings.md234-262ownership_invalid_binding - Missing binding in intermediate component packages/svelte/messages/client-warnings/warnings.md226-232Warnings about SSR/client mismatches:
hydration_mismatch - DOM structure mismatch during hydration packages/svelte/messages/client-warnings/warnings.md204-212hydration_attribute_changed - Attribute value changed between renders packages/svelte/messages/client-warnings/warnings.md143-171hydration_html_changed - {@html} value changed between renders packages/svelte/messages/client-warnings/warnings.md173-202Sources: packages/svelte/messages/client-warnings/warnings.md1-344
The script generates reference documentation alongside the runtime code, ensuring that error documentation stays synchronized with the implementation.
Documentation files are generated in documentation/docs/98-reference/.generated/ packages/svelte/scripts/process-messages/index.js74-93:
###)```)<!-- This file is generated by scripts/process-messages/index.js. Do not edit! -->Generated documentation structure documentation/docs/98-reference/.generated/client-errors.md97-139:
Sources: packages/svelte/scripts/process-messages/index.js74-93 documentation/docs/98-reference/.generated/client-errors.md1-300
The runtime integrates error functions at validation points. For example, keyed each blocks validate key stability packages/svelte/tests/runtime-runes/samples/each-key-volatile/_config.js1-11:
When a keyed each block uses a non-idempotent key expression (like [item.group, item.id] which creates a new array each time), the runtime detects this and throws each_key_volatile packages/svelte/tests/runtime-runes/samples/each-key-volatile/main.svelte8-10
Development-mode code instruments operations to detect warning conditions. The equality checking system patches array methods to detect proxy comparison issues packages/svelte/src/internal/client/dev/equality.js4-69:
This detects when developers compare $state proxies with their underlying values, which always returns false due to proxy identity packages/svelte/tests/runtime-runes/samples/state-proxy-equality-mismatch/_config.js21-25
Sources: packages/svelte/src/internal/client/dev/equality.js4-69 packages/svelte/tests/runtime-runes/samples/state-proxy-equality-mismatch/_config.js1-41
Refresh this wiki