Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

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

Offen
  • Stimmt etwas nicht?
#9,920 4 Kommentare 3 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

@byungsker arbeitet bereits daran.

Seit 25.4.2026.

  • #1 von @byungsker — ohne Merge geschlossen
  • #2 von @byungsker — offen
  • #10573 von @byungsker — offen
  • #11252 von @adityachaudhary99 — ohne Merge geschlossen

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
48/100
Issue-Typ
Bug
Klarheit
Größtenteils klar
Aktivitätsstatus
Ruhig
Tech-Stack
typescript
Bereich
frontend

Rechercherichtung

Beginne mit der verlinkten CodeSandbox und ihrer Reproduktion in src/Post.vue und verfolge dann die TypeScript-Überladungen, die queryOptions und useQuery im Vue-Adapter verwenden. Bestätige den Fix, indem der gebrandete queryKey-Helfer ohne TS2769 kompiliert, während die funktionierenden fetchQuery- und inline-useQuery-Fälle erhalten bleiben.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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

Vorherrschende Sprache
TypeScript
Sterne
50.4k
Forks
4.2k
Ø Merge
11 Std. 33 Min.
Gemergte PRs (30 T.)
421

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus TanStack/query

Alle Issues in TanStack/query

Ähnliche Issues

Weitere Issues zu TypeScript

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.