TRPCError code mismatch when client and server share AppRouter type but handle NOT_FOUND differently

Answer

No – the shared AppRouter type does not automatically constrain the error union to the specific TRPCError codes a procedure may throw. Without an explicit error shape, the client infers the error as TRPCError<unknown>, so compile‑time checking cannot enforce handling of NOT_FOUND versus other codes.

Confirmed facts

• tRPC v10+ allows attaching an errorShape or meta to a procedure to describe the possible error codes.
• When errorShape is omitted, the generated client type for a procedure is TRPCError<unknown> (generic).
• Using a const enum for error codes and referencing it in both server throws and client switch enables exhaustive handling with a default: never case.

Recommended pattern (steps)

1. Define a const enum (or as const object) of the error codes you intend to use, e.g. enum AppErrorCode { NotFound = 'NOT_FOUND', Unauthorized = 'UNAUTHORIZED' }.
2. On the server, throw using the enum: throw new TRPCError({ code: AppErrorCode.NotFound }).
3. Attach an errorShape (or meta({ possibleCodes: AppErrorCode }) as const) to the procedure so the client type becomes a union of specific TRPCError<AppErrorCode.NotFound> etc.
4. On the client, infer the procedure type via typeof appRouter.procedures['myProc'] and catch the error; then switch on error.code with cases for each enum value and a default: never to achieve exhaustiveness.

Verification

Create two test procedures, one throwing NOT_FOUND and another UNAUTHORIZED. In your IDE, hover over the call site; without errorShape you will see TRPCError<unknown>. After adding the shape, the hover shows a union like TRPCError<'NOT_FOUND'> | TRPCError<'UNAUTHORIZED'>. At runtime, a switch (error.code) with cases for each enum and a default: never will compile only if all codes are covered.