A hydrated query that rejects ignores the reader's `retry` and `retryDelay`

Aberta
#12,529 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

@KATT já está trabalhando nisso.

Desde 3/11/2026.

Avaliação

Dificuldade
3/5
Tempo estimado
1-2 dias
Facilidade para iniciantes
45/100
Tipo de issue
Bug
Clareza
Claramente especificada
Status de atividade
Ativa
Stack de tecnologia
typescript

Direção de pesquisa

Start with the query-core retryer and hydration flow described in the issue: hydrate resumes the pending query before a QueryObserver exists, so later observer options may not reach the retryer. The issue says fix #12511 implements the desired precedence; inspect that change and the related query-core tests. Done means the repro succeeds with reader retry and retryDelay, while unset options still use hydrate options and client defaults.

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

Descrição

(🤖 Drafted with Opus 5.5, then read and edited word by word by me.)

Describe the bug

If the server dehydrates a query that's still pending, hydrate resumes it in the browser before any component reads it. If that promise rejects, the retries use the options the fetch started with - the hydrate options and the client's defaults. The retry and retryDelay the reader sets are ignored, even if the reader mounted before the promise settled.

So a reader can't recover from a failed server fetch:

  • Client default retry: false, reader sets retry: 1: the query never retries. It ends in error with the message redacted, since dehydrate redacts the server's error.
  • Reader sets retry: false: the query still retries, after the client's default delay of about a second.
  • Reader sets retryDelay: 10: the retry still waits about a second.
Your minimal, reproducible example
Steps to reproduce
  1. Open the StackBlitz link. It installs deps, runs npm start by itself and prints the output in the terminal. Or clone the repo and run npm install && npm start.
  2. npm start runs this repro.ts with tsx, against @tanstack/[email protected]:
import {
  QueryClient,
  QueryObserver,
  defaultShouldDehydrateQuery,
  dehydrate,
  hydrate,
} from '@tanstack/query-core'

const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
const queryKey = ['post', 1]

// 🖥️ Server: the query is still pending at dehydrate, and rejects later
const serverClient = new QueryClient({
  defaultOptions: {
    dehydrate: {
      // include pending queries in dehydration, as in the Advanced SSR guide
      shouldDehydrateQuery: (query) =>
        defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
    },
  },
})
serverClient
  .query({
    queryKey,
    queryFn: () => sleep(10).then(() => Promise.reject(new Error('server error'))),
    retry: false,
  })
  .catch(() => {})
const dehydratedState = dehydrate(serverClient)

// 🌐 Browser: retries are off by default, so we can see whether the reader's option wins
const browserClient = new QueryClient({
  defaultOptions: { queries: { retry: false } },
})
hydrate(browserClient, dehydratedState)

// 👀 This reader asks for 1 retry
const observer = new QueryObserver(browserClient, {
  queryKey,
  queryFn: () => sleep(10).then(() => 'data from the browser'),
  retry: 1,
  retryDelay: 10,
})
observer.subscribe(() => {})

await sleep(500)
const { status, data, error } = browserClient.getQueryState(queryKey)!
console.log({ status, data, error: error?.message })
// ✅ Expected: { status: 'success', data: 'data from the browser', error: undefined }
// 🐛 Actual on 5.106.0: { status: 'error', data: undefined, error: 'redacted' }
process.exit(0)
  1. It prints { status: 'error', data: undefined, error: 'redacted' }. The reader's retry: 1 never ran.
Expected behavior

I'd expect a hydrated query that rejects to retry with its reader's retry and retryDelay, like any other fetch. The script should print { status: 'success', data: 'data from the browser', error: undefined }. Today it keeps the client's defaults and ends with the redacted server error.

Options the reader doesn't set should still come from the hydrate options first and the client's defaults second, like now.

How often does this bug happen?

Every time

Screenshots or Videos

None - the script's output above shows the result.

Platform
  • OS: any. I reproduced it on Linux.
  • Runtime: Node 22.23.4. It also runs in StackBlitz's WebContainer. The bug is in query-core, so the browser doesn't matter.
Tanstack Query adapter

vanilla

TanStack Query version

v5.106.0

TypeScript version

7.0.2

Additional context
  • React hits the same bug: useQuery and useSuspenseQuery under HydrationBoundary read the query through a QueryObserver.
  • hydrate resumes a pending query with query.fetch(undefined, { initialPromise }) before any observer exists. The retryer reads retry and retryDelay from the options that fetch started with, so options an observer sets later never reach it.
  • Fix in #12511: when a fetch resumes a hydrated promise, the retryer uses the retry and retryDelay an observer set itself, then the hydrate options, then the client's defaults. With it, the script above prints { status: 'success', data: 'data from the browser', error: undefined }.
Linguagem predominante
TypeScript
Estrelas
50.6k
Forks
4.2k
Merge médio
9h 50min
PRs com merge (30d)
310

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/query

Todas as issues de TanStack/query

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.