⚠️ ORPC Returning Array of Errors When Using TanStack Query Retries

[girishcx07]

Hello team 👋,

I’m currently using ORPC within a Turborepo setup powered by Next.js, integrated with TanStack Query for client-side data fetching.

In my setup, ORPC handlers internally call APIs (through custom API handlers). This structure works perfectly for me, as my project’s backend is large and cannot be modified directly due to organizational bandwidth constraints. So far, ORPC has been a great fit for bridging server and client requests cleanly.

However, I’ve encountered one issue:

When a query fails and TanStack Query retries (default 3 attempts), after all retry attempts fail, the returned error becomes an array of errors instead of a single ORPC error object.
This breaks my expected error structure, since my components are designed to handle a single ORPC error, not an array.

Here’s my main question:

• Is this array of errors generated by TanStack Query’s retry mechanism, or is it coming from ORPC’s internal error propagation?
• If this behavior originates from ORPC, is there a recommended way to handle or normalize this scenario?

This is currently my only major concern. Apart from this, ORPC has proven to be an excellent solution for managing server-client API interactions efficiently.

Thanks in advance for any clarification or suggestions 🙏

[dosubot[bot]]

Hi @girishcx07! I'm Dosu and I’m helping the orpc team.

The array of errors you’re seeing after TanStack Query retries is generated by TanStack Query’s retry mechanism, not by ORPC itself. ORPC is designed to propagate a single error object per failed request—its error handling logic (including custom error classes, interceptors, and serialization) always returns a single error, not an array. TanStack Query, however, aggregates errors from each failed retry attempt and returns them as an array if all attempts fail source.

To normalize this in your components, you can extract the last error from the array (which is usually the most relevant), or map the array to a single error object that matches your expected structure. For example:

const normalizedError = Array.isArray(error) ? error[error.length - 1] : error;
// Now handle normalizedError as a single ORPC error object

This will ensure your error handling logic remains consistent. If you want more type safety or custom normalization, you can also use ORPC’s safe function or error type predicates as described in the docs source.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[girishcx07]

Hi @dosu 👋 — thanks a lot for the detailed explanation!

That clears things up — it’s helpful to know that the array of errors I’m seeing after multiple retry attempts is coming from TanStack Query’s retry mechanism, not from ORPC itself. The normalization approach you suggested (extracting the last error from the array) works well for now 🙏

However, I wanted to check if ORPC provides any middleware-like mechanism or lifecycle hook that would allow me to intercept and normalize this array of errors centrally before the response reaches the client.

In my previous setup (using TanStack Query directly with APIs), I never encountered this issue because my API responses were already wrapped in a consistent format. But now, since I’m using ORPC handlers directly, it would be great to have a centralized place—similar to middleware or interceptors—where I can handle and convert the array of errors into a single structured ORPC error object.

If ORPC supports such a mechanism, I’d be glad to explore it further. It would definitely help keep the integration cleaner and more maintainable for large-scale projects.

Thanks again for the guidance and for clarifying the source of the issue 🙏

[dosubot[bot]]

Yes, ORPC supports middleware and lifecycle hooks that let you centrally intercept and normalize errors before they reach the client. You can use the .use() method to add middleware to your handlers, and inside the middleware, catch errors thrown by downstream handlers or other middleware, then transform or normalize them as needed—such as converting unexpected errors into a consistent ORPC error object or mapping custom errors to your preferred format. This pattern is documented and widely used for centralized error handling in ORPC (docs, middleware docs, discussion).

For example:

const errorNormalizer = os.middleware(async ({ next, errors }) => {
  try {
    return await next();
  } catch (err) {
    // Normalize error here
    if (Array.isArray(err)) {
      // If TanStack Query aggregates errors, pick the last one or map as needed
      throw errors.INTERNAL_SERVER_ERROR({ message: err[err.length - 1]?.message || 'Unknown error' });
    }
    if (!(err instanceof ORPCError)) {
      throw errors.INTERNAL_SERVER_ERROR({ message: err?.message || 'Unknown error' });
    }
    throw err;
  }
});

const api = os
  .use(errorNormalizer)
  .handler(async ({ input }) => {
    // your handler logic
  });

You can also use built-in hooks like onError for global error interception (docs). If you want to handle error normalization on the client side, ORPC provides the safe function and error type predicates for consistent error handling (client error handling).

In summary: you can implement centralized error normalization in ORPC using middleware or interceptors, and this is the recommended approach for keeping your integration clean and maintainable.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[unnoq]

Hi @girishcx07

In my previous setup (using TanStack Query directly with APIs), I never encountered this issue because my API responses were already wrapped in a consistent format.

I don't think so, this is tanstack query behavior for sure, and what you expected from normal fetch vs through orpc should be the same.

[girishcx07]

Thanks