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

Formatting Errors and Field-Level Validation Feedback

Customize how tRPC errors are shaped and surface clean field-level validation messages to your client.

Formatting Errors and Field-Level Validation Feedback is a free tRPC End-to-End Type Safe APIs lesson on CoddyKit — lesson 4 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 Format Errors?

You can throw and catch tRPC errors. But clients often need structured error data, especially field-level messages from validation, to show next to form inputs.

The errorFormatter Option

tRPC lets you customize the error shape globally with errorFormatter when initializing.

const t = initTRPC.create({
  errorFormatter({ shape }) {
    return shape;
  },
});

Detecting Zod Errors

When a Zod input fails, tRPC attaches it as the error cause. You can detect and expose it.

import { ZodError } from "zod";

errorFormatter({ shape, error }) {
  const isZod = error.cause instanceof ZodError;
  return { ...shape, data: { ...shape.data, isZod } };
}

Adding Flattened Field Errors

Zod can flatten issues into a fieldErrors map that maps each field to its messages.

const zodError = error.cause instanceof ZodError
  ? error.cause.flatten().fieldErrors
  : null;
return { ...shape, data: { ...shape.data, zodError } };

What the Client Receives

The client now gets a structured object it can attach to form fields.

// e.g. { zodError: { email: ["Invalid email"] } }

Reading Errors on the Client

Catch the error and read the formatted data.

try {
  await client.signup.mutate(input);
} catch (err) {
  const fields = err.data?.zodError;
  // show fields.email next to the input
}

HTTP Status Codes

The shape includes a code that maps to an HTTP status, useful for clients reacting to UNAUTHORIZED vs BAD_REQUEST.

// shape.data.code === "BAD_REQUEST"
// shape.data.httpStatus === 400

Not Leaking Internals

Be careful: do not expose stack traces or internal messages in production. Format errors to reveal only safe, user-facing details.

Logging the Raw Error

Log the full error server-side for debugging while sending a sanitized version to the client.

errorFormatter({ shape, error }) {
  console.error(error); // full detail in server logs
  return shape;        // safe shape to client
}

Consistent Error Contract

A consistent error shape across all procedures means your frontend can handle errors with one reusable helper.

Reusing a Client Helper

Because every procedure shares the same error shape, write one helper that extracts fieldErrors and a top-level message for any failed call.

function parseError(err) {
  return { fields: err.data?.zodError, message: err.message };
}

Quick Check

Test your error formatting knowledge.

Recap

You learned to deliver great error feedback:

  • errorFormatter customizes the error shape globally
  • Detect ZodError causes and expose fieldErrors
  • Log full detail server-side, send a sanitized shape to clients

Well-shaped errors make forms and clients dramatically easier to build.

Frequently asked questions

Is the “Formatting Errors and Field-Level Validation Feedback” lesson free?

Yes — the full text of “Formatting Errors and Field-Level Validation Feedback” 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 “Formatting Errors and Field-Level Validation Feedback”?

Customize how tRPC errors are shaped and surface clean field-level validation messages to your client. 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 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Formatting Errors and Field-Level Validation Feedback” 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