InvalidLiveQueryReturnError

What this error means and what can trigger it

Copied link.

InvalidLiveQueryReturnError means a server-side Query.live handler returned something for which Effect's Stream.isStream predicate is false. That includes arrays, native iterables, Promises, scalars, null, generator objects, and even an effect that later succeeds with a Stream. The handler boundary wants the Stream itself.

Native sources are still usable, although they must first be wrapped with Stream.fromIterable, Stream.fromAsyncIterable, or another Stream constructor. The public handler type expresses this requirement already; the runtime guard is there for JavaScript, unsafe casts, and compiler or integration mismatches.

Exactly where it triggers

Copied link.

if (!is_live_source(source)) {
	throw new InvalidLiveQueryReturnError();
}

At that point, the wrapper invokes the handler synchronously, passes its immediate return value into this validator, and catches the thrown class. Helper normalization returns existing Error instances unchanged, so the async remote wrapper's Promise rejects with InvalidLiveQueryReturnError.

For reference, the class itself is declared at modules/svelte-effect-runtime/src/errors.ts L501 @ C14.

Why this is the case

Copied link.

SER converts the returned Stream from Effect into an async iterable while providing the request event and server runtime. That conversion preserves the Stream's typed failures, environment requirements, interruption, and resource scopes.

A native iterable does not carry those effect semantics, while an effect that merely produces a Stream adds another execution layer the wrapper does not flatten. Requiring the Stream at the handler boundary makes the server-to-SvelteKit conversion unambiguous.