0Pricing
tRPC End-to-End Type Safe APIs · Lesson

Custom Error Types

Define and throw custom error types from your backend that are correctly propagated to the frontend.

Custom Error Types is a free tRPC End-to-End Type Safe APIs lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the tRPC End-to-End Type Safe APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Custom Error Types?

In tRPC, we often use TRPCError for handling issues. But sometimes, you need more specific error types.

  • Clarity: Custom errors make your code clearer about what went wrong.
  • Specific Handling: Allows the frontend to react differently to distinct error conditions.
  • Better Debugging: Provides more context than a generic error.

Let's learn how to define and use them!

Basic Custom Error Class

At its simplest, a custom error is a class that extends JavaScript's built-in Error class. This ensures it behaves like a standard error.

It usually takes a message and sets its own name property.

class MyCustomError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'MyCustomError';
  }
}

function main() {
  try {
    throw new MyCustomError('Something specific went wrong!');
  } catch (error) {
    if (error instanceof MyCustomError) {
      console.log(`Caught: ${error.name} - ${error.message}`);
    } else {
      console.log(`Caught generic error: ${error.message}`);
    }
  }
}

main();

tRPC's TRPCError

For tRPC to correctly understand and propagate errors, your custom errors should extend TRPCError from @trpc/server.

TRPCError requires an object with a code (e.g., 'NOT_FOUND', 'BAD_REQUEST') and a message. This code helps the client understand the error type.

Defining a tRPC Custom Error

Here's how you define a custom error for tRPC, ensuring it extends TRPCError and sets a relevant status code.

This example creates a UserNotFoundError. Notice we pass the tRPC code to the super() constructor.

import { TRPCError } from '@trpc/server';

class UserNotFoundError extends TRPCError {
  constructor(userId: string) {
    super({
      code: 'NOT_FOUND',
      message: `User with ID '${userId}' not found.`
    });
    this.name = 'UserNotFoundError';
  }
}

function main() {
  try {
    throw new UserNotFoundError('user-123');
  } catch (error) {
    if (error instanceof TRPCError) {
      console.log(`Error Code: ${error.code}`);
      console.log(`Error Message: ${error.message}`);
    }
  }
}

main();

Throwing Custom Errors (Backend)

Once defined, you can throw your custom error directly within your tRPC procedures (queries or mutations). tRPC will automatically catch it and send it to the client.

This allows your backend logic to signal specific issues clearly.

import { publicProcedure, router } from './trpc'; // Assume trpc setup
import { TRPCError } from '@trpc/server';

class UserNotFoundError extends TRPCError {
  constructor(userId: string) {
    super({ code: 'NOT_FOUND', message: `User ${userId} not found.` });
    this.name = 'UserNotFoundError';
  }
}

const appRouter = router({
  getUser: publicProcedure
    .input(z.string())
    .query(async ({ input: userId }) => {
      // Simulate database lookup
      if (userId === 'nonexistent') {
        throw new UserNotFoundError(userId); // Throw our custom error!
      }
      return { id: userId, name: `User ${userId}` };
    }),
});

// Note: `z` for Zod input validation is assumed here
// The router itself is not runnable without a full server context.

Frontend: Receiving Errors

On the frontend, when a tRPC procedure fails, the client-side tRPC library will throw an instance of TRPCClientError.

This error object contains the code and message from your backend TRPCError, allowing you to identify the specific issue.

Frontend: Identifying Custom Errors

To handle specific custom errors on the client, you can use a try...catch block and inspect the error object.

  • Check error.data.code: This is the most reliable way as it's directly from the TRPCError code.
  • Check error.message: Less reliable, but can be used for specific messages.
  • instanceof (with shared types): If you share the custom error class definition between client and server, you can use instanceof. This is common in monorepos.

Frontend Example: Handling UserNotFoundError

Here's how a React component (or similar frontend logic) might handle our UserNotFoundError using the error.data.code property.

This allows you to display a user-friendly message specific to the error.

import { trpc } from './utils/trpc'; // Assume trpc client setup

function UserProfile({ userId }: { userId: string }) {
  const { data, error, isLoading } = trpc.getUser.useQuery(userId);

  if (isLoading) {
    return '<p>Loading user data...</p>';
  }

  if (error) {
    if (error.data?.code === 'NOT_FOUND') {
      return `<p>User with ID <b>${userId}</b> does not exist.</p>`;
    } else {
      return `<p>An unexpected error occurred: ${error.message}</p>`;
    }
  }

  return `<h1>Welcome, ${data?.name}!</h1>`;
}

function main() {
  // This function simulates component usage.
  // In a real app, trpc.getUser.useQuery would trigger an API call.
  console.log('Simulating UserProfile for existing user...');
  // Assume UserProfile('user-123') would render 'Welcome, User user-123!'

  console.log('Simulating UserProfile for nonexistent user...');
  // Assume UserProfile('nonexistent') would render 'User with ID nonexistent does not exist.'
}

main();

Quick Check

Which of the following are good reasons to define and use custom error types in tRPC, especially when extending TRPCError?

Recap: Custom Error Types

Great job! You've learned how to leverage custom error types in tRPC:

  • Extend TRPCError: For tRPC to correctly propagate your errors.
  • Specify code: Use tRPC's error codes (e.g., 'NOT_FOUND') for standardization.
  • Throw on Backend: Signal specific issues from your procedures.
  • Catch on Frontend: Use error.data.code for precise error handling.

This approach leads to more robust and user-friendly applications by clearly communicating backend issues to the client.

Frequently asked questions

Is the “Custom Error Types” lesson free?

Yes — the full text of “Custom Error Types” is free to read here on the web, and the tRPC End-to-End Type Safe APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the tRPC End-to-End Type Safe APIs course, upgrade to CoddyKit PRO.

What will I learn in “Custom Error Types”?

Define and throw custom error types from your backend that are correctly propagated to the frontend. You practise tRPC End-to-End Type Safe APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start tRPC End-to-End Type Safe APIs?

No prior experience is required. tRPC End-to-End Type Safe APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Custom Error Types” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this tRPC End-to-End Type Safe APIs lesson?

Yes. Every tRPC End-to-End Type Safe APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Handling tRPC Errors Gracefully
  2. Custom Error Types
  3. Data Transformers for Serialization
  4. Formatting Errors and Field-Level Validation Feedback
← Back to tRPC End-to-End Type Safe APIs