TanStack · TkDodo · Jan 8, 2023 · Dec 25, 2022 · Dec 26, 2022 · Dec 26, 2022
diff --git a/docs/react/guides/migrating-to-react-query-5.md b/docs/react/guides/migrating-to-react-query-5.md
@@ -140,6 +140,24 @@ You can achieve the same functionality by passing a function to `structuralShari
 
 To make the `useErrorBoundary` prop more framework-agnostic and avoid confusion with the established React function prefix "`use`" for hooks and the "ErrorBoundary" component name, it has been renamed to `throwErrors` to more accurately reflect its functionality.
 
+### `Error` is now the default type for errors instead of `unknown`
+
+Even though in JavaScript, you can `throw` anything (which makes `unknown` the most correct type), almost always, `Errors` (or subclasses of `Error`) are thrown. This change makes it easier to work with the `error` field in TypeScript for most cases.
+
+If you want to throw something that isn't an Error, you'll now have to set the generic for yourself:
+
+```ts
+useQuery<number, string>({
+  queryKey: ['some-query'],
+  queryFn: async () => {
+      if (Math.random() > 0.5) {
+        throw 'some error'
+      }
+      return 42
+  }
+})
+```
+
 ### eslint `prefer-query-object-syntax` rule is removed
 
 Since the only supported syntax now is the object syntax, this rule is no longer needed
diff --git a/packages/query-core/src/infiniteQueryObserver.ts b/packages/query-core/src/infiniteQueryObserver.ts
@@ -23,7 +23,7 @@ type InfiniteQueryObserverListener<TData, TError> = (
 
 export class InfiniteQueryObserver<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = Error,
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,

diff --git a/packages/query-core/src/mutation.ts b/packages/query-core/src/mutation.ts
@@ -22,7 +22,7 @@ interface MutationConfig<TData, TError, TVariables, TContext> {
 
 export interface MutationState<
   TData = unknown,
-  TError = unknown,
+  TError = Error,
   TVariables = void,
   TContext = unknown,
 > {
@@ -84,7 +84,7 @@ export type Action<TData, TError, TVariables, TContext> =
 
 export class Mutation<
   TData = unknown,
-  TError = unknown,
+  TError = Error,
   TVariables = void,
   TContext = unknown,
 > extends Removable {

diff --git a/packages/query-core/src/mutationCache.ts b/packages/query-core/src/mutationCache.ts
@@ -130,7 +130,7 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     return this.mutations
   }
 
-  find<TData = unknown, TError = unknown, TVariables = any, TContext = unknown>(
+  find<TData = unknown, TError = Error, TVariables = any, TContext = unknown>(
     filters: MutationFilters,
   ): Mutation<TData, TError, TVariables, TContext> | undefined {
     if (typeof filters.exact === 'undefined') {

diff --git a/packages/query-core/src/mutationObserver.ts b/packages/query-core/src/mutationObserver.ts
@@ -27,7 +27,7 @@ interface NotifyOptions {
 
 export class MutationObserver<
   TData = unknown,
-  TError = unknown,
+  TError = Error,
   TVariables = void,
   TContext = unknown,
 > extends Subscribable<

diff --git a/packages/query-core/src/query.ts b/packages/query-core/src/query.ts
@@ -36,7 +36,7 @@ interface QueryConfig<
   state?: QueryState<TData, TError>
 }
 
-export interface QueryState<TData = unknown, TError = unknown> {
+export interface QueryState<TData = unknown, TError = Error> {
   data: TData | undefined
   dataUpdateCount: number
   dataUpdatedAt: number
@@ -67,7 +67,7 @@ export interface FetchContext<
 
 export interface QueryBehavior<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = Error,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > {
@@ -140,7 +140,7 @@ export interface SetStateOptions {
 
 export class Query<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = Error,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > extends Removable {

diff --git a/packages/query-core/src/queryCache.ts b/packages/query-core/src/queryCache.ts
@@ -147,7 +147,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
 
   get<
     TQueryFnData = unknown,
-    TError = unknown,
+    TError = Error,
     TData = TQueryFnData,
     TQueyKey extends QueryKey = QueryKey,
   >(
@@ -160,7 +160,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     return this.queries
   }
 
-  find<TQueryFnData = unknown, TError = unknown, TData = TQueryFnData>(
+  find<TQueryFnData = unknown, TError = Error, TData = TQueryFnData>(
     filters: WithRequired<QueryFilters, 'queryKey'>,
   ): Query<TQueryFnData, TError, TData> | undefined {
     if (typeof filters.exact === 'undefined') {

diff --git a/packages/query-core/src/queryClient.ts b/packages/query-core/src/queryClient.ts
@@ -187,7 +187,7 @@ export class QueryClient {
     )
   }
 
-  getQueryState<TQueryFnData = unknown, TError = undefined>(
+  getQueryState<TQueryFnData = unknown, TError = Error>(
     queryKey: QueryKey,
   ): QueryState<TQueryFnData, TError> | undefined {
     return this.queryCache.find<TQueryFnData, TError>({ queryKey })?.state
@@ -286,7 +286,7 @@ export class QueryClient {
 
   fetchQuery<
     TQueryFnData,
-    TError,
+    TError = Error,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
@@ -308,7 +308,7 @@ export class QueryClient {
 
   prefetchQuery<
     TQueryFnData = unknown,
-    TError = unknown,
+    TError = Error,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
@@ -319,7 +319,7 @@ export class QueryClient {
 
   fetchInfiniteQuery<
     TQueryFnData,
-    TError,
+    TError = Error,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
@@ -331,7 +331,7 @@ export class QueryClient {
 
   prefetchInfiniteQuery<
     TQueryFnData,
-    TError,
+    TError = Error,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
@@ -455,11 +455,11 @@ export class QueryClient {
   }
 
   defaultQueryOptions<
-    TQueryFnData,
-    TError,
-    TData,
-    TQueryData,
-    TQueryKey extends QueryKey,
+    TQueryFnData = unknown,
+    TError = Error,
+    TData = TQueryFnData,
+    TQueryData = TQueryFnData,
+    TQueryKey extends QueryKey = QueryKey,
   >(
     options?:
       | QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>

diff --git a/packages/query-core/src/queryObserver.ts b/packages/query-core/src/queryObserver.ts
@@ -40,7 +40,7 @@ export interface ObserverFetchOptions extends FetchOptions {
 
 export class QueryObserver<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = Error,
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,

diff --git a/packages/query-core/src/retryer.ts b/packages/query-core/src/retryer.ts
@@ -5,7 +5,7 @@ import type { CancelOptions, NetworkMode } from './types'
 
 // TYPES
 
-interface RetryerConfig<TData = unknown, TError = unknown> {
+interface RetryerConfig<TData = unknown, TError = Error> {
   fn: () => TData | Promise<TData>
   abort?: () => void
   onError?: (error: TError) => void
@@ -28,14 +28,14 @@ export interface Retryer<TData = unknown> {
 
 export type RetryValue<TError> = boolean | number | ShouldRetryFunction<TError>
 
-type ShouldRetryFunction<TError> = (
+type ShouldRetryFunction<TError = Error> = (
   failureCount: number,
   error: TError,
 ) => boolean
 
 export type RetryDelayValue<TError> = number | RetryDelayFunction<TError>
 
-type RetryDelayFunction<TError = unknown> = (
+type RetryDelayFunction<TError = Error> = (
   failureCount: number,
   error: TError,
 ) => number
@@ -63,7 +63,7 @@ export function isCancelledError(value: any): value is CancelledError {
   return value instanceof CancelledError
 }
 
-export function createRetryer<TData = unknown, TError = unknown>(
+export function createRetryer<TData = unknown, TError = Error>(
   config: RetryerConfig<TData, TError>,
 ): Retryer<TData> {
   let isRetryCancelled = false

diff --git a/packages/query-core/src/tests/mutations.test.tsx b/packages/query-core/src/tests/mutations.test.tsx
@@ -325,7 +325,7 @@ describe('mutations', () => {
       context: undefined,
       variables: undefined,
       data: 'new',
-      error: undefined,
+      error: null,
       failureCount: 0,
       failureReason: null,
       isPaused: false,

diff --git a/packages/query-core/src/tests/queriesObserver.test.tsx b/packages/query-core/src/tests/queriesObserver.test.tsx
@@ -303,7 +303,7 @@ describe('queriesObserver', () => {
 
     const newQueryObserver = new QueryObserver<
       unknown,
-      unknown,
+      Error,
       unknown,
       unknown,
       QueryKey