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

Branded queryKey in queryOptions causes TS error (TS2769) in useQuery

Abierto
  • ¿Algo no está bien?
#9,920 4 comentarios 3 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@byungsker ya está trabajando en esto.

Desde el 25/4/2026.

  • #1 de @byungsker — cerrado sin fusionar
  • #2 de @byungsker — abierto
  • #10573 de @byungsker — abierto
  • #11252 de @adityachaudhary99 — cerrado sin fusionar

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
48/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
typescript
Área
frontend

Línea de trabajo

Comienza con el CodeSandbox enlazado y su reproducción en src/Post.vue; después, sigue las sobrecargas de TypeScript que usan queryOptions y useQuery en el adaptador de Vue. Confirma el arreglo haciendo que el helper queryKey con marca compile sin TS2769, manteniendo los casos funcionales de fetchQuery y de useQuery inline.

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

Descripción

package: vue-query
Describe the bug

I’m encountering a TypeScript overload mismatch (TS2769) when calling useQuery() with the result of a queryOptions(...) function whose returned object contains a queryKey with a branded type. The error occurs specifically when useQuery() receives the output of queryOptions(...) containing a branded value in queryKey.

Passing the same options to queryClient.fetchQuery(queryOptions(queryKey: brandedKey, queryFn)) — works fine.
Passing the branded key inline to useQuery (i.e. useQuery({ queryKey: brandedKey, queryFn})) — works fine.

Your minimal, reproducible example

https://codesandbox.io/p/devbox/tanstack-query-ts-error-2769-forked-spc8jh?file=%2Fsrc%2FPost.vue

Steps to reproduce

1. Define a branded type in your code:

type PostId = string & { readonly __brand: "PostId" };

2. Create a helper function that returns queryOptions where the queryKey includes a value using this branded type:

const getPostQueryOptions = (
  params: MaybeRefOrGetter<{ postId: PostId }>
) => {
  return queryOptions({
    queryKey: ["post", params],
    queryFn: () => fetcher(toValue(params).postId),
  });
};

3. Call useQuery() using the result of this helper:

useQuery(getPostQueryOptions({ postId }));

4. Observe the TypeScript error:
No overload matches this call.
Overload 1 of 3, '(options: DefinedInitialQueryOptions<Post, Error, Post, MaybeRefDeep<string | (() => { postId: PostId; }) | { postId: PostId; }>[]>, queryClient?: QueryClient | undefined): UseQueryDefinedReturnType<...>', gave the following error.... ts(2769)

Expected behavior

useQuery() should correctly accept a QueryOptions object whose queryKey contains a branded (nominal) type.

In other words:
Passing the result of queryOptions(...) or any helper function that returns a QueryOptions object should not trigger a TypeScript overload error, even if the queryKey includes branded values.

How often does this bug happen?

Every time

Screenshots or Videos
Image Image
Platform
  • OS [Windows]
  • Browser [Chrome]
Tanstack Query adapter

vue-query

TanStack Query version

v5.85.3

TypeScript version

v5.9.2

Additional context

No response

Lenguaje dominante
TypeScript
Estrellas
50.4k
Forks
4.2k
Merge medio
11 h 33 min
PR fusionados (30 d)
421

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

Todos los issues de TanStack/query

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.