SerovalUnsupportedTypeError when TanStack Start SSR dehydrates an on-demand query collection

Start with the reproduction by running npm install and node index.js, then trace metadata from packages/query-db-collection/src/query.ts through packages/query-core/src/hydration.ts. Read the expression structures in packages/db/src/query/ir.ts and compare them with the SSR serialization path described in the issue. Done means the on-demand collection dehydrates and serializes successfully, allowing SSR hydration without the SerovalUnsupportedTypeError.

• I've validated the bug against the latest version of DB packages

Describe the bug

SSR breaks with SerovalUnsupportedTypeError when a syncMode: "on-demand" query collection is used with @tanstack/react-router-ssr-query (setupRouterSsrQueryIntegration).

query-db-collection stores LoadSubsetOptions on the TanStack Query cache entry as meta.loadSubsetOptions. Those options contain the expression IR classes (Func, PropRef, Value) from @tanstack/db and a live AbortSignal. @tanstack/query-core's dehydrateQuery copies meta into the dehydrated state, and @tanstack/router-core serializes the router payload with seroval.crossSerializeStream. Seroval has no plugin for the IR classes or for AbortSignal, so it throws on the first Func node.

Server log:

Serialization error: SerovalUnsupportedTypeError: Seroval Error (specific: 1)
    at parseObjectPhase2 (seroval/dist/index.js:2783:8)
    ...
  value: Func { name: 'and', args: [ [Func], [Func] ], type: 'func' }

The dev server then reports [vite] Internal server error: socket hang up and the request 500s.

To Reproduce

StackBlitz: link

Or locally:

1. npm install
2. node index.js

The script creates an on-demand query collection, runs a live query with two .where() calls, dehydrates the QueryClient, and feeds the result to seroval.crossSerializeStream with the same options shape @tanstack/router-core uses (refs, onSerialize, onError, onDone).

Output:

queryFn received where: Func and

query.meta.loadSubsetOptions keys: [ 'where', 'signal', 'orderBy', 'limit' ]
  where: Func and
  signal: AbortSignal

seroval.crossSerializeStream(dehydratedRouter) <- TanStack Start SSR serialization:
  FAILED: Seroval Error (specific: 1)
  offending value: Func {
  name: 'and',
  args: [
    Func { name: 'eq', args: [Array], type: 'func' },
    Func { name: 'eq', args: [Array], type: 'func' }
  ],
  type: 'func'
}

Expected behavior

The dehydrated state for a query collection should serialize like any other cached query, so SSR hydration works.

Screenshots

Not applicable. The failure is server-side and the terminal output is above.

Desktop

• OS: Linux (Ubuntu devcontainer)
• Browser: not applicable, the failure happens during SSR
• Version: Node v24.21.0, npm 11.19.0

Smartphone

Not applicable.

Additional context

Versions (all current latest): @tanstack/db 0.9.2, @tanstack/query-db-collection 1.2.15, @tanstack/query-core 5.104.0, @tanstack/router-core 1.171.33, @tanstack/router-ssr-query-core 1.169.3, seroval 1.6.8.

Where the meta comes from (packages/query-db-collection/src/query.ts):

function getLoadSubsetOptionsForMeta(
  opts: LoadSubsetOptions,
): Omit<LoadSubsetOptions, `subscription` | `refetch`> {
  const {
    subscription: _subscription,
    refetch: _refetch,
    ...serializableOptions
  } = opts
  return serializableOptions
}

subscription and refetch are removed, and the rest is named serializableOptions. What remains includes where, orderBy, and cursor (instances of Func / PropRef / Value, see packages/db/src/query/ir.ts) plus signal, an AbortSignal. The copy becomes extendedMeta.loadSubsetOptions on the QueryObserver, so it ends up at query.meta.loadSubsetOptions.

Dehydration keeps it (packages/query-core/src/hydration.ts):

...(query.meta && { meta: query.meta }),

@tanstack/router-ssr-query-core dehydrates every query into dehydratedData.query.initial and the query stream. @tanstack/router-core serializes that payload with crossSerializeStream and ssrSerovalPlugins (ShallowErrorPlugin, RawStreamSSRPlugin, ReadableStreamPlugin). None of those plugins handle the IR classes, and the set has no AbortSignal plugin, although one exists in seroval-plugins/web. seroval.serialize({ s: new AbortController().signal }) throws for the same reason.

PR #1644 / issue #901 covered structuredClone-based persisters. structuredClone drops prototypes and on Node accepts the AbortSignal, so those persisters pass, while the Seroval path still fails. The two consumers need different handling.

Possible fixes:

• Strip signal from the meta copy. Query functions already receive a signal through the Query function context.
• Store the expression tree as plain serializable nodes. parseWhereExpression and parseOrderByExpression read type / name / args / path / value, so plain objects keep working for ctx.meta.loadSubsetOptions.
• Alternatively keep subset state out of meta, or add a serializeMeta hook to the dehydration path.

Workaround in an app:

setupRouterSsrQueryIntegration({
  router,
  queryClient,
  dehydrateOptions: {
    shouldDehydrateQuery: (query) => {
      const options = query.meta?.loadSubsetOptions
      return !options?.where && !options?.orderBy?.length && !options?.cursor && !options?.signal
    },
  },
})

That keeps plain and eager-collection queries in the SSR payload and lets the on-demand ones refetch in the browser.