From f483daf7995bdb92e89c9f209a5991d070e504b5 Mon Sep 17 00:00:00 2001
From: benjosua <ben.script@protonmail.com>
Date: Sun, 8 Mar 2026 23:05:10 +0100
Subject: [PATCH] docs: add description for derived_references_self error

---
 .../98-reference/.generated/client-errors.md  | 29 +++++++++++++++++++
 .../svelte/messages/client-errors/errors.md   | 29 +++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/documentation/docs/98-reference/.generated/client-errors.md b/documentation/docs/98-reference/.generated/client-errors.md
index 7fccac5808..1e5ec12914 100644
--- a/documentation/docs/98-reference/.generated/client-errors.md
+++ b/documentation/docs/98-reference/.generated/client-errors.md
@@ -52,6 +52,35 @@ See the [migration guide](/docs/svelte/v5-migration-guide#Components-are-no-long
 A derived value cannot reference itself recursively
 ```
 
+This error occurs when a [`$derived`](/docs/svelte/$derived) value reads itself during its computation, either directly or indirectly. This creates a circular dependency.
+
+Often, this happens when trying to accumulate a value or preserve previous state, such as tracking a high score:
+
+```svelte
+<script>
+	var score = $state(0);
+
+	// Error: `highscore` tries to read its own value to compute the new one
+	var highscore = $derived(Math.max(score, highscore ?? 0));
+</script>
+```
+
+To fix this, use a regular [`$state`](/docs/svelte/$state) variable and update it explicitly alongside the source state (for example, in an event handler):
+
+```svelte
+<script>
+	let score = $state(0);
+	let highscore = $state(0);
+
+	function addScore(points) {
+		score += points;
+		highscore = Math.max(score, highscore);
+	}
+</script>
+```
+
+This error can also happen indirectly with circular component bindings, such as when a parent component computes a prop by reading a bound value from a child component that in turn depends on that prop.
+
 ### each_key_duplicate
 
 ```
diff --git a/packages/svelte/messages/client-errors/errors.md b/packages/svelte/messages/client-errors/errors.md
index 3f20cb989d..c39178431c 100644
--- a/packages/svelte/messages/client-errors/errors.md
+++ b/packages/svelte/messages/client-errors/errors.md
@@ -36,6 +36,35 @@ See the [migration guide](/docs/svelte/v5-migration-guide#Components-are-no-long
 
 > A derived value cannot reference itself recursively
 
+This error occurs when a [`$derived`](/docs/svelte/$derived) value reads itself during its computation, either directly or indirectly. This creates a circular dependency.
+
+Often, this happens when trying to accumulate a value or preserve previous state, such as tracking a high score:
+
+```svelte
+<script>
+	var score = $state(0);
+
+	// Error: `highscore` tries to read its own value to compute the new one
+	var highscore = $derived(Math.max(score, highscore ?? 0));
+</script>
+```
+
+To fix this, use a regular [`$state`](/docs/svelte/$state) variable and update it explicitly alongside the source state (for example, in an event handler):
+
+```svelte
+<script>
+	let score = $state(0);
+	let highscore = $state(0);
+
+	function addScore(points) {
+		score += points;
+		highscore = Math.max(score, highscore);
+	}
+</script>
+```
+
+This error can also happen indirectly with circular component bindings, such as when a parent component computes a prop by reading a bound value from a child component that in turn depends on that prop.
+
 ## each_key_duplicate
 
 > Keyed each block has duplicate key at indexes %a% and %b%