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

Activity

1. DamianOsipiuk

   added

   package: vue-query

   on Nov 27, 2025
2. DamianOsipiuk commented on Nov 27, 2025

   

   DamianOsipiuk

   on Nov 27, 2025

   Last edited by DamianOsipiuk

   Contributor

   More actions

   Hmm it seems that branded type is conflicting with DataTag. If i remove it from queryOptions signature then TS error goes away.

   Not sure about the fix.
3. byungsker

   added a commit that references this issue on Apr 25, 2026

   fix(vue-query): preserve branded types in MaybeRefDeep

   ...

   This issue will close once commit 2b87d91 is merged into the 'main' branch.

   2b87d91
4. xerox0213 commented on May 14, 2026

   

   xerox0213

   on May 14, 2026

   Last edited by xerox0213

   More actions

   I'm experiencing a similar TS2769 error when spreading queryOptions with an extra enabled property inside a Vue computed():

   useQuery(
     computed(() => ({
       ...myQueryOptions(params),
       enabled: someCondition,
     }))
   )

   Error: Type '(string | number)[]' is missing the following properties from type '... & { [dataTagSymbol]: ...; [dataTagErrorSymbol]: ...; }': [dataTagSymbol], [dataTagErrorSymbol]
5. KIM-DONGJU commented on May 20, 2026

   

   KIM-DONGJU

   on May 20, 2026

   More actions

   Additional production data point that may help prioritize this:

   We just attempted to upgrade @tanstack/vue-query from 5.97.0 → 5.100.11 on a Nuxt 4 codebase (~24 files using the spread-and-override pattern). The upgrade is blocked specifically by this regression, and the impact is narrow but real:

   Impact in our codebase: 3 out of 24 spread-and-override hooks fail TS2769. The other 21 happen to pass because their type shape doesn't trigger the issue.

   Pattern that fails:

   useQuery({
     ...someQueries.x(),     // queryOptions(...) return value
     staleTime: 5 * MINUTE,
     enabled,
   })

   Failing cases share at least one of these traits (based on bisecting which 3 of 24 fail):

   1. Response data is a primitive (e.g. boolean) — dataTagSymbol: boolean brand on the queryKey seems particularly fragile through MaybeRefDeep mapping
   2. refetchInterval is set alongside the spread — its generic instantiation re-references the branded queryKey shape, triggering the mismatch

   Workaround we shipped: dropping the spread in favor of explicit field forwarding works around it:

   const opts = someQueries.x()
   useQuery({
     queryKey: opts.queryKey,
     queryFn: opts.queryFn,
     staleTime: 5 * MINUTE,
     enabled,
   })

   Property access preserves the branded queryKey type, while spread + extra props loses it through MaybeRefDeep. This matches the root cause #10573 identifies.

   We're unblocked via the workaround, but having #10573 (or equivalent) land would let us delete the explicit-field workaround and restore the idiomatic spread pattern — which is what the official TanStack Vue docs recommend.

   Happy to share the failing file paths / a minimal repro if it helps. The reproduction in the issue body already covers the essential case; this is mostly a "+1, real-world frequency" data point.
6. byungsker

   added a commit that references this issue on Jul 22, 2026

   fix(vue-query): preserve branded types in MaybeRefDeep

   ...

   This issue will close once commit af629b6 is merged into the 'main' branch.

   af629b6
7. basuneko commented on Sep 22, 2026

   

   basuneko

   on Sep 22, 2026

   More actions

   I'm upgrading from 5.92 and seeing something similar.

   Although I don't use branded types; my issue manifests when using keys containing a ref/computed.
   The issue first appeared on 5.95 and it still occurs on 5.102.8.

   For me, wrapping the whole query key in a computed fixes and unwrapping the param seems to have helped 🤞

   // before: 
   function myQueryOptions(foo: MaybeRef<string>) {
     queryOptions({
       queryKey: ['bar', toRef(foo)] // ❌ this fails
       ...
     })
   }
   
   //after
   function myQueryOptions(foo: MaybeRef<string>) {
     queryOptions({
       queryKey: computed(() => ['bar', toValue(foo)]) // ✅ this seems works
       ...
     })
   }