Branded queryKey in queryOptions causes TS error (TS2769) in useQuery
维护者通常 1 天内回复
@byungsker 已经在做这个了。
开始于 2026年4月25日。
评估
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 新手友好度
- 48/100
- Issue 类型
- 缺陷
- 描述清晰度
- 基本清楚
- 活跃度
- 冷清
- 技术栈
- typescript
- 领域
- frontend
调研方向
先从链接的 CodeSandbox 及其在 src/Post.vue 中的复现开始，然后跟踪 Vue 适配器中 queryOptions 和 useQuery 使用的 TypeScript 重载。通过让 branded queryKey helper 在没有 TS2769 的情况下通过编译来确认修复，同时保留正常工作的 fetchQuery 和 inline useQuery 场景。
由索引模型根据 Issue 内容生成。
描述
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
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
- 主要语言
- TypeScript
- 星标
- 50.4k
- 派生
- 4.2k
- 平均合并
- 7 小时 29 分钟
- 30 天内合并 PR
- 393
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
TanStack/query 的其他 Issue
-
solid-query: STRICT_READ_UNTRACKED on Solid 2 — client()/options() read in component body (useMutation, useBaseQuery)可能重新可做 关联的 PR 已关闭且未合并。 未关闭
难度 2/5 1-3 小时 新手友好度 84/100
TanStack/query#11358 · 2 条评论 · 1 个 reaction ·
维护者通常 1 天内回复
-
solid-query: switching the queryClient accessor strands the new client's cache (subscription stays on the old observer)可能已有人在做 @MaNaN1803 于 75 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 84/100
TanStack/query#11106 · 1 条评论 ·
维护者通常 1 天内回复
-
restoreQueries and persisterGc throw on malformed persisted entries可能已有人在做 @VGontier-cmd 今天认领。 未关闭
难度 3/5 1-2 天 新手友好度 72/100
维护者通常 1 天内回复
-
难度 4/5 3-5 天 新手友好度 45/100
维护者通常 1 天内回复
-
setQueryData: NoInfer loses discriminated-union members when spreading a narrowed updater value可能已有人在做 @iosayin 于 2 天前认领。 未关闭
难度 4/5 3-5 天 新手友好度 55/100
维护者通常 1 天内回复
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 85/100
Comfy-Org/ComfyUI_frontend#20346 ·
维护者通常 1 天内回复
-
难度 1/5 1 小时以内 新手友好度 90/100
decentralized-identity/didwebvh-ts#203 ·
维护者通常 1 天内回复
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
难度 2/5 1-3 小时 新手友好度 65/100
lingdojo/kana-dojo#31791 · 1 条评论 · 5 个 reaction ·
维护者通常 1 天内回复
-
Telegram webhook: line breaks lost since switch to rich messages可能已有人在做 @Kshot3000 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 82/100
维护者通常 1 天内回复
-
github_actions security
难度 2/5 1-3 小时 新手友好度 75/100
维护者通常 1 天内回复