Skip to content

docs(react-query): recommend defaultError = unknown instead of AxiosError #9575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TkDodo merged 7 commits into from
Aug 18, 2025
+28 −10
Merged

docs(react-query): recommend defaultError = unknown instead of AxiosError #9575

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8b85d83
docs(react-query): recommend defaultError = unknown instead of AxiosE…
leesb971204 Aug 18, 2025
acbad31
docs(react-query): clarify usage of defaultError in global Error type…
leesb971204 Aug 18, 2025
61e46a9
Merge branch 'main' into docs/typescript
TkDodo Aug 18, 2025
ba4a117
ci: apply automated fixes
autofix-ci[bot] Aug 18, 2025
84a63d8
docs(solid-query): recommend defaultError = unknown instead of AxiosE…
leesb971204 Aug 18, 2025
b675c8d
docs(angular-query): recommend defaultError = unknown instead of Axio…
leesb971204 Aug 18, 2025
c66177a
docs(vue-query): add example code for Registering a global Error
leesb971204 Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/framework/angular/typescript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,8 @@ import '@tanstack/angular-query-experimental'

declare module '@tanstack/angular-query-experimental' {
interface Register {
defaultError: AxiosError
// Use unknown so call sites must narrow explicitly.
defaultError: unknown
}
}

Expand All @@ -164,7 +165,7 @@ const query = injectQuery(() => ({

computed(() => {
const error = query.error()
// ^? error: AxiosError | null
// ^? error: unknown | null
})
```

Expand Down
7 changes: 4 additions & 3 deletions docs/framework/react/typescript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ if (axios.isAxiosError(error)) {

### Registering a global Error

TanStack Query v5 allows for a way to set a global Error type for everything, without having to specify generics on call-sides, by amending the `Register` interface. This will make sure inference still works, but the error field will be of the specified type:
TanStack Query v5 allows for a way to set a global Error type for everything, without having to specify generics on call-sides, by amending the `Register` interface. This will make sure inference still works, but the error field will be of the specified type. If you want to enforce that call-sides must do explicit type-narrowing, set `defaultError` to `unknown`:

[//]: # 'RegisterErrorType'

Expand All @@ -139,12 +139,13 @@ import '@tanstack/react-query'

declare module '@tanstack/react-query' {
interface Register {
defaultError: AxiosError
// Use unknown so call sites must narrow explicitly.
defaultError: unknown
}
}

const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const error: AxiosError | null
// ^? const error: unknown | null
```

[//]: # 'RegisterErrorType'
Expand Down
11 changes: 6 additions & 5 deletions docs/framework/solid/typescript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,16 +129,15 @@ if (axios.isAxiosError(query.error)) {

[typescript playground](https://www.typescriptlang.org/play/?#code/JYWwDg9gTgLgBAbzgYygUwIYzQRQK5pQCecAvnAGZQQhwDkAAjBgHYDOzyA1gPRsQAbYABMAtAEcCxOgFgAUKEiw4GAB7AIbStVp01GtrLnyYRMGjgBxanjBwAvIjgiAXHBZ4QAI0Jl585Ah2eAo0GGQAC2sIWy1HAAoASjcABR1gNjQAHmjbAG0AXQA+BxL9TQA6AHMw+LoeKpswQ0SKmAi0Fnj0Nkh2C3sSnr7MiuEsDET-OUDguElCEkdUTGx8Rfik0rh4hHk4A-mpIgBpNCI3PLpGmOa6AoAaOH3DheIAMRY3UPCoprYHvJSIkpsY5G8iBVCNQoPIeDxDnAAHoAfmmwAoO3KbAqGQAgupNABRKAw+IQqGk6AgxAvA4U6HQOlweGI1FA+RAA)

## Registering a global `Error`

TanStack Query v5 allows for a way to set a global Error type for everything, without having to specify generics on call-sides, by amending the `Register` interface. This will make sure inference still works, but the error field will be of the specified type:
[//]: # 'RegisterErrorType'

```tsx
import '@tanstack/solid-query'

declare module '@tanstack/solid-query' {
interface Register {
defaultError: AxiosError
// Use unknown so call sites must narrow explicitly.
defaultError: unknown
}
}

Expand All @@ -148,9 +147,11 @@ const query = useQuery(() => ({
}))

query.error
// ^? (property) error: AxiosError | null
// ^? (property) error: unknown | null
```

[//]: # 'RegisterErrorType'

## Registering global `Meta`

Similarly to registering a [global error type](#registering-a-global-error) you can also register a global `Meta` type. This ensures the optional `meta` field on [queries](../reference/useQuery.md) and [mutations](../reference/useMutation.md) stays consistent and is type-safe. Note that the registered type must extend `Record<string, unknown>` so that `meta` remains an object.
Expand Down
15 changes: 15 additions & 0 deletions docs/framework/vue/typescript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,21 @@ if (error.value instanceof Error) {
[//]: # 'TypingError3'
[//]: # 'TypingError3'
[//]: # 'RegisterErrorType'

```tsx
import '@tanstack/vue-query'

declare module '@tanstack/vue-query' {
interface Register {
// Use unknown so call sites must narrow explicitly.
defaultError: unknown
}
}

const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const error: unknown | null
```
Comment on lines +103 to +105
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

❓ Verification inconclusive

Fix Vue type hint: error is a Ref — show Ref<unknown | null> instead of unknown | null

In @tanstack/vue-query, fields returned from useQuery are Refs. The current hint drops the Ref wrapper and can confuse readers. It should be Ref<unknown | null>.

Apply this diff:

-//      ^? const error: unknown | null
+//      ^? const error: Ref<unknown | null>

Follow-up: Earlier in this page, the “TypingError” example shows Ref<unknown> (without | null). For consistency and accuracy, consider updating that hint to Ref<unknown | null> as well.

Fix Vue Query useQuery error type hint to use Ref

  • In docs/framework/vue/typescript.md at line 103, update the inferred type comment for error: 
    -//      ^? const error: unknown | null
+//      ^? const error: Ref<unknown | null>
  • Follow-up: earlier “TypingError” example currently shows Ref<unknown>—consider changing it to Ref<unknown | null> for consistency and accuracy.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const error: unknown | null
```
const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const error: Ref<unknown | null>
🤖 Prompt for AI Agents 
In docs/framework/vue/typescript.md around lines 103 to 105, the inline type
comment for the `error` returned from useQuery is incorrect: change the hint
from `const error: unknown | null` to `const error: Ref<unknown | null>` so it
reflects Vue's ref wrapper, and update the earlier “TypingError” example to use
`Ref<unknown | null>` instead of `Ref<unknown>` for consistency and accuracy.


[//]: # 'RegisterErrorType'
[//]: # 'TypingMeta'
[//]: # 'TypingMeta'
Expand Down
Loading