Error Handling

Error Formatting

Added in v5.2

You can customize the server-side behavior in your API handler's options by using an error formatter.

By default, only the error message is returned to the client, to avoid leaking any sensitive information. You can customize this behavior by specifying the errorFormatter option when you initialize your file route helper. An error formatter runs on the server and takes the original UploadThingError, and returns a JSON-serializable object. The error also includes a cause property which contains more information about the nature of the error and what caused the error to throw in the first place.

For example, if you're using Zod as an input parser, you can return information of what fields failed validation by checking if the cause is a ZodError. Zod provides a flatten method that returns a JSON-serializable object which we can return to the client.

import * as z from "zod";
 
import { createUploadthing } from "uploadthing/next";
import type { FileRouter } from "uploadthing/next";
 
const f = createUploadthing({
  errorFormatter: (err) => {
    return {
      message: err.message,
      zodError: err.cause instanceof z.ZodError ? err.cause.flatten() : null,
    };
  },
});
 
export const uploadRouter = {
  withInput: f(["image"]).input(z.object({ foo: z.string() })),
  //  ...
} satisfies FileRouter;

Catching errors on the client

You can catch errors on the client by using the onUploadError property on the premade components, or the useUploadthing hook. You can access the JSON object that you returned from your error formatter on the data property:

<UploadButton
  endpoint="withInput"
  input={{ foo: userInput }}
  onUploadError={(error) => {
    console.log("Error: ", error);
    const fieldErrors = error.data?.zodError?.fieldErrors;
    //                              ^? typeToFlattenedError
    setError(fieldErrors.foo[0] ?? "");
  }}
/>