From 13ae09b861a2f62ab75cafc054c246255b727266 Mon Sep 17 00:00:00 2001
From: paoloricciuti <ricciutipaolo@gmail.com>
Date: Tue, 31 Mar 2026 10:26:24 +0200
Subject: [PATCH] fix: throw descriptive error if using `createRawSnippet`
 using custom renderer

---
 .../98-reference/.generated/client-errors.md     |  6 ++++++
 packages/svelte/messages/client-errors/errors.md |  4 ++++
 .../src/internal/client/dom/blocks/snippet.js    |  5 ++++-
 packages/svelte/src/internal/client/errors.js    | 16 ++++++++++++++++
 .../samples/raw-snippet/_config.js               |  5 +++++
 .../samples/raw-snippet/main.svelte              |  9 +++++++++
 6 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 packages/svelte/tests/custom-renderers/samples/raw-snippet/_config.js
 create mode 100644 packages/svelte/tests/custom-renderers/samples/raw-snippet/main.svelte

diff --git a/documentation/docs/98-reference/.generated/client-errors.md b/documentation/docs/98-reference/.generated/client-errors.md
index 7fccac5808..4c6361af46 100644
--- a/documentation/docs/98-reference/.generated/client-errors.md
+++ b/documentation/docs/98-reference/.generated/client-errors.md
@@ -197,6 +197,12 @@ Failed to hydrate the application
 Could not `{@render}` snippet due to the expression being `null` or `undefined`. Consider using optional chaining `{@render snippet?.()}`
 ```
 
+### invalid_snippet_in_custom_renderer
+
+```
+`createRawSnippet` cannot be used with a custom renderer
+```
+
 ### lifecycle_legacy_only
 
 ```
diff --git a/packages/svelte/messages/client-errors/errors.md b/packages/svelte/messages/client-errors/errors.md
index 3f20cb989d..a047c04571 100644
--- a/packages/svelte/messages/client-errors/errors.md
+++ b/packages/svelte/messages/client-errors/errors.md
@@ -151,6 +151,10 @@ This can happen if you render a hydratable on the client that was not rendered o
 
 > Could not `{@render}` snippet due to the expression being `null` or `undefined`. Consider using optional chaining `{@render snippet?.()}`
 
+## invalid_snippet_in_custom_renderer
+
+> `createRawSnippet` cannot be used with a custom renderer
+
 ## lifecycle_legacy_only
 
 > `%name%(...)` cannot be used in runes mode
diff --git a/packages/svelte/src/internal/client/dom/blocks/snippet.js b/packages/svelte/src/internal/client/dom/blocks/snippet.js
index 343d510e72..961a56acf7 100644
--- a/packages/svelte/src/internal/client/dom/blocks/snippet.js
+++ b/packages/svelte/src/internal/client/dom/blocks/snippet.js
@@ -16,6 +16,7 @@ import { DEV } from 'esm-env';
 import { get_first_child, get_next_sibling, insert_before, node_type } from '../operations.js';
 import { prevent_snippet_stringification } from '../../../shared/validate.js';
 import { BranchManager } from './branches.js';
+import { renderer } from '../../custom-renderer/state.js';
 
 /**
  * @template {(node: TemplateNode, ...args: any[]) => void} SnippetFn
@@ -71,9 +72,11 @@ export function wrap_snippet(component, fn) {
  * @returns {Snippet<Params>}
  */
 export function createRawSnippet(fn) {
-	// TODO RENDERER: throw an error for createRawSnippet in a non-browser environment, as it relies on DOM APIs
 	// @ts-expect-error the types are a lie
 	return (/** @type {TemplateNode} */ anchor, /** @type {Getters<Params>} */ ...params) => {
+		if (renderer != null) {
+			e.invalid_snippet_in_custom_renderer();
+		}
 		var snippet = fn(...params);
 
 		/** @type {Element} */
diff --git a/packages/svelte/src/internal/client/errors.js b/packages/svelte/src/internal/client/errors.js
index d60c2dd280..facfd18e26 100644
--- a/packages/svelte/src/internal/client/errors.js
+++ b/packages/svelte/src/internal/client/errors.js
@@ -361,6 +361,22 @@ export function invalid_snippet() {
 	}
 }
 
+/**
+ * `createRawSnippet` cannot be used with a custom renderer
+ * @returns {never}
+ */
+export function invalid_snippet_in_custom_renderer() {
+	if (DEV) {
+		const error = new Error(`invalid_snippet_in_custom_renderer\n\`createRawSnippet\` cannot be used with a custom renderer\nhttps://svelte.dev/e/invalid_snippet_in_custom_renderer`);
+
+		error.name = 'Svelte error';
+
+		throw error;
+	} else {
+		throw new Error(`https://svelte.dev/e/invalid_snippet_in_custom_renderer`);
+	}
+}
+
 /**
  * `%name%(...)` cannot be used in runes mode
  * @param {string} name
diff --git a/packages/svelte/tests/custom-renderers/samples/raw-snippet/_config.js b/packages/svelte/tests/custom-renderers/samples/raw-snippet/_config.js
new file mode 100644
index 0000000000..aa4c289bde
--- /dev/null
+++ b/packages/svelte/tests/custom-renderers/samples/raw-snippet/_config.js
@@ -0,0 +1,5 @@
+import { test } from '../../test';
+
+export default test({
+	error: '`createRawSnippet` cannot be used with a custom renderer'
+});
diff --git a/packages/svelte/tests/custom-renderers/samples/raw-snippet/main.svelte b/packages/svelte/tests/custom-renderers/samples/raw-snippet/main.svelte
new file mode 100644
index 0000000000..e1cf5c9b19
--- /dev/null
+++ b/packages/svelte/tests/custom-renderers/samples/raw-snippet/main.svelte
@@ -0,0 +1,9 @@
+<script>
+	import { createRawSnippet } from 'svelte';
+
+	const snippet = createRawSnippet(() => ({
+		render: () => `<span>hello</span>`
+	}));
+</script>
+
+{@render snippet()}