How do you return data while throwing an error?

[mintydev789]

I have a custom error class I created for my server function errors, and I extended it with an optional data field for returning some data while throwing the error. This can be useful for cases where, for example, you want to return the user the updated state if the state they see in the browser is out-of-date, meaning that their original request should now be considered stale.

import "server-only";
import { createSafeActionClient, DEFAULT_SERVER_ERROR_MESSAGE } from "next-safe-action";
import z from "zod/v4";
import { authClient } from "~/helpers/authClient.ts";
import { authorizeUser } from "./serverUtilityFunctions.ts";

export const actionClient = createSafeActionClient({
  defineMetadataSchema() {
    return z.object({
      // null means the user simply needs to be logged in; undefined means authorization isn't necessary
      permissions: z.any().nullable().optional(),
    });
  },
  handleServerError(e) {
    console.error("Action error:", e.message);

    if (e instanceof CcActionError) return e;

    return new CcActionError(DEFAULT_SERVER_ERROR_MESSAGE);
  },
}).use<{ session: typeof authClient.$Infer.Session }>(async ({ next, metadata }) => {
  // We still want to check authentication when permissions = null
  if (metadata.permissions !== undefined) {
    const session = await authorizeUser({ permissions: metadata.permissions });

    return next({ ctx: { session } });
  } else {
    return next();
  }
});

export class CcActionError extends Error {
  data?: any;

  constructor(message: string, options?: { data: any }, ...rest: any[]) {
    super(message, ...rest);

    this.name = "CcActionError";
    if (options) {
      this.data = options.data;
    }
  }
}

Originally, this worked just fine, and I was able to access the full error object on the frontend, including the data field, but for some reason it no longer works for me on v8.0.2 (not sure if it's due to a recent update though). Is there a "proper" way for returning data when throwing errors in next-safe-action?

[TheEdoRan]

Hey, I'm really curious to know how you used to add fields to the Error class, because as far as I know, React removes all additional fields to make the error serializable, so it can be sent to the client. You can find more information about this here:

• [BUG] Not possible to handle errors that are not instance of Error #314 (comment)
• rethrowing the error in handleReturnedServerError loses the orignal error #244

[TheEdoRan]

Yes, as explained here.

[mintydev789]

Yes, as explained here.

Yeah, that's the part of the docs I was following. It says "It's used to customize logging and the shape of the server error returned to the client", and I was trying to do the error shape customization part, but I guess it doesn't work with React's serialization. So how else can you customize the shape?

[TheEdoRan]

You return it inside the serverError prop as an object, with the customized shape. For instance, you can throw a CustomError inside an action, then check for that class inside handleServerError, and then add that field to serverError, with the additional data.

[mintydev789]

You return it inside the serverError prop as an object, with the customized shape. For instance, you can throw a CustomError inside an action, then check for that class inside handleServerError, and then add that field to serverError, with the additional data.

Ohh, I think I get it. So I should've been returning actual objects instead of custom error objects. I think it would be useful to add a small section to that part of the docs, showing how you can return additional data with your server errors, because the way it is, it seems like you just have to return a string with the error message.

[TheEdoRan]

Good call, will update it. You can return anything from that function, the type is a generic and will change if you return something different than a string.