Add a warning when the misuse of reset in an error:boundary causes an error to be thrown when flushing the boundary content

Author: raythurnvoid

documentation/docs/98-reference/.generated/client-warnings.md

@@ -200,6 +200,74 @@ Consider the following code:
 
 To fix it, either create callback props to communicate changes, or mark `person` as [`$bindable`]($bindable).
 
+### reset_misuse
+
+```
+reset() was invoked and the `<svelte:boundary>` template threw during flush. Calling `reset` inside the `onerror` handler while the app state is still broken can cause the fresh template to crash during its first render; the error bypassed the <svelte:boundary> to avoid an infinite loop `error` → `reset` → `error`
+```
+
+When you call `reset()` Svelte tears down the template inside `<svelte:boundary>` and renders a fresh one. If the same bad state that caused the first error in the first place is still present, that fresh mount crashes immediately. To break a potential `error → reset → error` loop, Svelte lets such render-time errors bubble past the boundary.
+
+Sometimes this happens because you might have called `reset` before the error was thrown (perhaps in the `onclick` handler of the button that will then trigger the error) or inside the `onerror` handler.
+
+`reset()` should preferably be called **after** the boundary has entered its error state. A common pattern is to call it from a "Try again" button in the fallback UI.
+
+If you need to call `reset` inside the `onerror` handler, ensure you fix the broken state first, *then* invoke `reset()`.
+
+The examples below show do's and don'ts:
+
+```svelte
+<!-- ❌ Don't call reset before errors occur -->
+<button onclick={() => {
+  showComponent = true;
+  if (reset) reset(); // Called before knowing if error will occur
+}}>
+  Update
+</button>
+
+<svelte:boundary>
+	{#if showComponent}
+		<!-- ... -->
+	{/if}
+</svelte:boundary>
+```
+
+```svelte
+<!-- ❌ Don't call reset without fixing the problematic state -->
+<svelte:boundary onerror={() => {
+	// Fix the problematic state first
+	reset(); // This will cause the error to be thrown again and bypass the boundary
+}}>
+	<!-- ... -->
+</svelte:boundary>
+```
+
+```svelte
+<!-- ✅ Call reset from error UI -->
+ <svelte:boundary>
+	<!-- ... -->
+
+	{#snippet failed(error)}
+		<button onclick={() => {
+			// Fix the problematic state first
+			selectedItem = null;
+			userInput = '';
+			reset(); // Now safe to retry
+		}}>Try Again</button>
+	{/snippet}
+</svelte:boundary>
+```
+
+```svelte
+<!-- ✅ Or fix the problematic state first and call reset in the onerror for immediate recovery -->
+<svelte:boundary onerror={() => {
+	componentState = initialComponentState; // Fix/reset the problematic state first
+	reset(); // Now the regular template will show without errors
+}}>
+	<!-- ... -->
+</svelte:boundary>
+```
+
 ### select_multiple_invalid_value
 
 ```

packages/svelte/messages/client-warnings/warnings.md

@@ -168,6 +168,72 @@ Consider the following code:
 
 To fix it, either create callback props to communicate changes, or mark `person` as [`$bindable`]($bindable).
 
+## reset_misuse
+
+> reset() was invoked and the `<svelte:boundary>` template threw during flush. Calling `reset` inside the `onerror` handler while the app state is still broken can cause the fresh template to crash during its first render; the error bypassed the <svelte:boundary> to avoid an infinite loop `error` → `reset` → `error`
+
+When you call `reset()` Svelte tears down the template inside `<svelte:boundary>` and renders a fresh one. If the same bad state that caused the first error in the first place is still present, that fresh mount crashes immediately. To break a potential `error → reset → error` loop, Svelte lets such render-time errors bubble past the boundary.
+
+Sometimes this happens because you might have called `reset` before the error was thrown (perhaps in the `onclick` handler of the button that will then trigger the error) or inside the `onerror` handler.
+
+`reset()` should preferably be called **after** the boundary has entered its error state. A common pattern is to call it from a "Try again" button in the fallback UI.
+
+If you need to call `reset` inside the `onerror` handler, ensure you fix the broken state first, *then* invoke `reset()`.
+
+The examples below show do's and don'ts:
+
+```svelte
+<!-- ❌ Don't call reset before errors occur -->
+<button onclick={() => {
+  showComponent = true;
+  if (reset) reset(); // Called before knowing if error will occur
+}}>
+  Update
+</button>
+
+<svelte:boundary>
+	{#if showComponent}
+		<!-- ... -->
+	{/if}
+</svelte:boundary>
+```
+
+```svelte
+<!-- ❌ Don't call reset without fixing the problematic state -->
+<svelte:boundary onerror={() => {
+	// Fix the problematic state first
+	reset(); // This will cause the error to be thrown again and bypass the boundary
+}}>
+	<!-- ... -->
+</svelte:boundary>
+```
+
+```svelte
+<!-- ✅ Call reset from error UI -->
+ <svelte:boundary>
+	<!-- ... -->
+
+	{#snippet failed(error)}
+		<button onclick={() => {
+			// Fix the problematic state first
+			selectedItem = null;
+			userInput = '';
+			reset(); // Now safe to retry
+		}}>Try Again</button>
+	{/snippet}
+</svelte:boundary>
+```
+
+```svelte
+<!-- ✅ Or fix the problematic state first and call reset in the onerror for immediate recovery -->
+<svelte:boundary onerror={() => {
+	componentState = initialComponentState; // Fix/reset the problematic state first
+	reset(); // Now the regular template will show without errors
+}}>
+	<!-- ... -->
+</svelte:boundary>
+```
+
 ## select_multiple_invalid_value
 
 > The `value` property of a `<select multiple>` element should be an array, but it received a non-array value. The selection will be kept as is.

packages/svelte/src/internal/client/dom/blocks/boundary.js

@@ -19,6 +19,7 @@ import {
 	set_hydrate_node
 } from '../hydration.js';
 import { queue_micro_task } from '../task.js';
+import * as w from '../../warnings.js';
 
 /**
  * @param {Effect} boundary
@@ -78,7 +79,13 @@ export function boundary(node, props, boundary_fn) {
 
 				with_boundary(boundary, () => {
 					is_creating_fallback = false;
-					boundary_effect = branch(() => boundary_fn(anchor));
+					try {
+						boundary_effect = branch(() => boundary_fn(anchor));
+					} catch (error) {
+						// If the new subtree immediately throws during mount, warn the dev.
+						w.reset_misuse();
+						throw error;
+					}
 				});
 			};
 

packages/svelte/src/internal/client/warnings.js

@@ -158,6 +158,17 @@ export function ownership_invalid_mutation(name, location, prop, parent) {
 	}
 }
 
+/**
+ * reset() was invoked and the `<svelte:boundary>` template threw during flush. Calling `reset` inside the `onerror` handler while the app state is still broken can cause the fresh template to crash during its first render; the error bypassed the <svelte:boundary> to avoid an infinite loop `error` → `reset` → `error`
+ */
+export function reset_misuse() {
+	if (DEV) {
+		console.warn(`%c[svelte] reset_misuse\n%creset() was invoked and the \`<svelte:boundary>\` template threw during flush. Calling \`reset\` inside the \`onerror\` handler while the app state is still broken can cause the fresh template to crash during its first render; the error bypassed the <svelte:boundary> to avoid an infinite loop \`error\` → \`reset\` → \`error\`\nhttps://svelte.dev/e/reset_misuse`, bold, normal);
+	} else {
+		console.warn(`https://svelte.dev/e/reset_misuse`);
+	}
+}
+
 /**
  * The `value` property of a `<select multiple>` element should be an array, but it received a non-array value. The selection will be kept as is.
  */