Bug Report: Response["error"] does not type all thrown errors (middleware/fetch errors missing)

[Mathieu-COSYNS]

openapi-react-query version

0.5.0

Description

The current implementation of error typing in useQuery, useMutation, and similar hooks only types the Response["error"] field returned by openapi-fetch. However, this does not account for:

• fetch-level errors (e.g. network errors)
• Errors thrown by custom middlewares
• Other runtime exceptions

As a result, the type assigned to the error field in React Query hooks is incomplete and potentially misleading, as consumers might assume that all thrown errors conform to Response["error"]. This typing issue can lead to subtle runtime bugs and TypeScript's false sense of safety. The type should be widened to reflect real-world thrown values.

Reproduction

Consider the following usage:

const { error } = useQueryClient.useQuery("get", "/some-endpoint");

if (error) {
  // TS assumes `error` is `Response["error"]`, e.g. an API error
  console.error(error);
}

But error could be any of the following:

• A error thrown by the fetch() call (e.g. network failure)
• A custom error thrown by a user-defined middleware
• ...

Yet, the generic types currently look like this:

UseQueryResult<TData, Response["error"]>

And Response["error"] is tied to what openapi-fetch returns — not all the above.

Expected result

React Query's error field should allow for a broader type to reflect all possible thrown errors.

We suggest modifying the generics to include unknown or Error union:

UseQueryResult<TData, Response["error"] | Error>

Or even more accurately:

UseQueryResult<TData, unknown>

This would better reflect the reality that many non-API errors can be thrown during the request lifecycle.

Proposed Fix

Update all references to the error field in the generics to broaden its type. For example:

UseQueryResult<..., unknown>
UseMutationResult<..., unknown, ...>

Alternatively, provide a customization hook or override so downstream users can define their own union error type.

Extra

• I’m willing to open a PR (see CONTRIBUTING.md)

[ajmanlove]

I hit up on this too and found it to be a bit of a double-bind. Error types do not reflect all thrown errors as stated above, but likewise supposedly successful response types also are not indicative of runtime. Consumers of the library can sorta account for one but not both in a way that retains the integrity of the typescript.

onSuccess(data) would type data Response["data"], but any 4XX and 5XX types that do not type as the Response["error"] or are not thrown by the fetch client would be invoked into the onSuccess callback at runtime (such as bland errors from things like proxies, load balancers, service-mesh layers, etc). This is given a nod in the docs

So neither the types of errors or successful response bodies are particularly runtime-realistic and they can create that false security.

I "solved" for this by ensuring one of my middlewares intercepts and throws all non response.ok responses with a custom error -- the net effect being now at least all my success response data types should be more or less runtime-accurate, but none of my error response types will be -- largely gutting what typescript safety-net there was in favor of convention.

export const errorHandlingMiddleware: Middleware = {
  async onResponse({ response }) {
    if (!response?.ok) {
      // Try to parse JSON, text, etc if able
     const errorBody = consumeResponseBody(response)

      // Throw an error that will be caught by openapi-react-query / openapi-fetch and quarantined from success callbacks
      throw new CustomFetchError(
        `Fetch Error with status: ${response.status}`,
        {
          status: response.status,
          body: errorData,
          response,
        }
      )
    }
  },
}

Unless there's a more elegant or idiomatic pattern that I'm missing (which could certainly be true), this seemed to be the most workable approach.

The ability to hint or extend the default generated types would be helpful in an approach like mine, since I could conceivably correct the error type.