ServerOnlyImportError

What this error means and what can trigger it

Copied link.

ServerOnlyImportError means a server-only export from the package root was invoked without SER's Vite rewrite replacing it with the implementation from svelte-effect-runtime/server. The error records the invoked export in export_name.

The root contains function placeholders for Query, Query.batch, Query.live, Command, Error, Form, Prerender, Redirect, RequestEvent, and get_server_runtime_or_throw; ServerRuntime.make uses a class placeholder instead. Those placeholders are reachable when the SER Vite plugin is missing, when a file falls outside the recognized server naming conventions, or when tooling executes the module without Vite's transform.

The rewrite recognizes *.server.ts, *.remote.ts, their module-suffix variants, and hooks.server.ts. It handles static imports, re-exports, and literal dynamic imports.

Exactly where it triggers

Copied link.

Every route constructs the error through:

function make_server_only_error(name: string): globalThis.Error {
	return new ServerOnlyImportError(name);
}

Function placeholders synchronously throw here:

function make_server_only_function(name: string): (...args: unknown[]) => never {
	return (..._args: unknown[]): never => {
		throw make_server_only_error(name);
	};
}

The ServerRuntime class placeholder throws from modules/svelte-effect-runtime/src/mod.ts L306 @ C4 when its static make method is called. For reference, the class itself is declared at modules/svelte-effect-runtime/src/errors.ts L757 @ C14.

Why this is the case

Copied link.

The root entrypoint must be importable by code that can enter a browser bundle. The real factories depend on SvelteKit server modules, request state, and server runtime services. Shipping those implementations through the universal root would weaken the server boundary.

The placeholders are named tripwires. Correctly transformed server files never execute them, whereas an untransformed call fails immediately with the exact export name instead of loading server code into an unsupported environment or producing an unrelated undefined-function error later.