Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

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

Fechada
  • Algo errado?
#1,950 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
52/100
Tipo de issue
Bug
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
react, typescript
Domínio
backend

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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

Linguagem predominante
TypeScript
Estrelas
3.9k
Forks
277
Merge médio
20h 31min
PRs com merge (30d)
228

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de TanStack/db

Todas as issues de TanStack/db

Issues semelhantes

Mais issues de TypeScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.