tRPC: Error Handling

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:

tRPC code	HTTP status
BAD_REQUEST	400
UNAUTHORIZED	401
FORBIDDEN	403
NOT_FOUND	404
CONFLICT	409
PRECONDITION_FAILED	412
UNPROCESSABLE_CONTENT	422
TOO_MANY_REQUESTS	429
INTERNAL_SERVER_ERROR	500

Error formatter: The errorFormatter function runs server-side after an error is thrown. It receives the default shape (code, message, data) and can augment it. The example above extracts ZodError.flatten() details into data.zodError so the client can display field-specific error messages.

cause for wrapping: Pass the original error as cause when wrapping: new TRPCError({ code: 'INTERNAL_SERVER_ERROR', cause: dbError }). The cause is accessible in errorFormatter for logging but is not sent to the client.

Client-side error.data: On the client, error.data contains the formatted server response (including zodError if you added it). error.message is the human-readable message. error.data?.code is the tRPC error code string.

onError on the router level: Configure a global onError in the tRPC HTTP adapter to log all procedure errors server-side. This is separate from the errorFormatter — onError is for side effects (logging to Sentry, Datadog), errorFormatter is for shaping the response.

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.