tRPC: Error Handling

Throw typed TRPCErrors in procedures and format them consistently for client consumption

When to Use

• Returning semantic HTTP-equivalent errors from tRPC procedures (404, 401, 422)
• Formatting error responses with additional metadata (field-level validation errors)
• Handling tRPC errors on the client in

  onError

  callbacks or error UI
• Logging server-side errors with request context (user ID, input, procedure name)
• Distinguishing between expected errors (validation, not found) and unexpected errors (database failures)

Instructions

1. Throw

   new TRPCError({ code: 'NOT_FOUND', message: '...' })

   for expected error conditions — it maps to the appropriate HTTP status.
2. Use

   code: 'UNAUTHORIZED'

   for unauthenticated requests and

   code: 'FORBIDDEN'

   for insufficient permissions.
3. Use

   code: 'BAD_REQUEST'

   for input that passes Zod schema validation but fails business rules.
4. Use

   code: 'UNPROCESSABLE_CONTENT'

   for field-level validation errors from Zod — pass the

   ZodError

   as

   cause

   .
5. Add an

   errorFormatter

   to

   initTRPC.create({ errorFormatter })

   to shape error responses and extract Zod validation details.
6. Handle errors on the client in

   onError

   callbacks of

   useMutation

   — check

   error.data?.code

   for the tRPC error code.
7. Never expose internal error messages or stack traces in

   INTERNAL_SERVER_ERROR

   responses — sanitize in the error formatter.

// server/trpc.ts — error formatter with Zod details
import { initTRPC, TRPCError } from '@trpc/server';
import { ZodError } from 'zod';
import superjson from 'superjson';

const t = initTRPC.context<TRPCContext>().create({
  transformer: superjson,
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        zodError: error.cause instanceof ZodError ? error.cause.flatten() : null,
      },
    };
  },
});

// server/routers/posts.ts — throwing typed errors
import { TRPCError } from '@trpc/server';

const postsRouter = router({
  getById: publicProcedure
    .input(z.object({ id: z.string().cuid() }))
    .query(async ({ ctx, input }) => {
      const post = await ctx.db.post.findUnique({ where: { id: input.id } });
      if (!post) {
        throw new TRPCError({
          code: 'NOT_FOUND',
          message: `Post ${input.id} not found`,
        });
      }
      if (post.status === 'draft' && ctx.session?.user.id !== post.authorId) {
        throw new TRPCError({ code: 'FORBIDDEN', message: 'Draft not accessible' });
      }
      return post;
    }),

  publish: protectedProcedure
    .input(z.object({ id: z.string().cuid() }))
    .mutation(async ({ ctx, input }) => {
      const post = await ctx.db.post.findUnique({ where: { id: input.id } });
      if (!post) throw new TRPCError({ code: 'NOT_FOUND' });
      if (post.authorId !== ctx.user.id) throw new TRPCError({ code: 'FORBIDDEN' });
      if (post.status === 'published') {
        throw new TRPCError({ code: 'BAD_REQUEST', message: 'Already published' });
      }
      return ctx.db.post.update({ where: { id: input.id }, data: { status: 'published' } });
    }),
});

// Client error handling
const { mutate } = api.posts.publish.useMutation({
  onError: (error) => {
    if (error.data?.code === 'FORBIDDEN') {
      toast.error('You do not have permission to publish this post');
    } else if (error.data?.zodError) {
      // Field-level errors from errorFormatter
      setFieldErrors(error.data.zodError.fieldErrors);
    } else {
      toast.error(error.message);
    }
  },
});

Details

tRPC error codes map to HTTP status codes. The mapping is deterministic and built in:

BAD_REQUEST

UNAUTHORIZED

FORBIDDEN

NOT_FOUND

CONFLICT

PRECONDITION_FAILED

UNPROCESSABLE_CONTENT

TOO_MANY_REQUESTS

INTERNAL_SERVER_ERROR

Error formatter: The

errorFormatter

shape

ZodError.flatten()

data.zodError

cause

cause

new TRPCError({ code: 'INTERNAL_SERVER_ERROR', cause: dbError })

cause

errorFormatter

Client-side

error.data

error.data

zodError

error.message

error.data?.code

onError

onError

errorFormatter

onError

errorFormatter

Source

https://trpc.io/docs/server/error-handling

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.
• related_skills: trpc-router-composition, trpc-input-validation, trpc-react-query-integration, next-error-boundaries, api-error-contracts, api-status-codes

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.