Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Cerrado
  • ¿Algo no está bien?
#1,950 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
52/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
react, typescript
Área
backend

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

  • 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.

Lenguaje dominante
TypeScript
Estrellas
4k
Forks
277
Merge medio
17 h 33 min
PR fusionados (30 d)
227

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de TanStack/db

Todos los issues de TanStack/db

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.