OpenAPI Contract First Error Question

[zacharyhansen]

Hi again!

I am not sure how to properly add the zod errors to the return of contract first implementation. For example I have a router defined like so

import { oc } from '@orpc/contract';
import { datasetContract } from './dataset/dataset.contract';

export const configurationContract = oc.router({
  dataset: oc.prefix('/dataset').router(datasetContract),
});

Then I implemented by contract using Nestjs

@Controller()
@Injectable()
export class DatasetController {
  constructor(private readonly datasetService: DatasetService) {}

  @Implement(configurationContract.dataset)
  dataset(
    @ClerkContext() clerk_claims: ClerkClaims,
    @AuthorizationContext() authorization: string,
  ) {
    return {
      byId: implement(configurationContract.dataset.byId).handler(
        async ({ input }) => {
          const dataset = await this.datasetService.dataset({
            datasetId: input.datasetId,
            organization_id: clerk_claims.organization_id,
            role_name: clerk_claims.o.rol,
          });
          console.log({ dataset: dataset.dataview?.dataview_column });
          return dataset;
        },
      ),

However I am getting a generic error like

{
  "defined": false,
  "code": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "message": "Output validation failed"
}

Which makes it difficult to debug. I can see how to define errors and throw errors in the contract implementation but I am not sure how to attach the zodErrors as data (ideally defining this once for my whole router) similar to this code in the docs

clientInterceptors: [
    onError((error) => {
      if (
        error instanceof ORPCError
        && error.code === 'BAD_REQUEST'
        && error.cause instanceof ValidationError
      ) {
        // If you only use Zod you can safely cast to ZodIssue[]
        const zodError = new ZodError(error.cause.issues as ZodIssue[])

        throw new ORPCError('INPUT_VALIDATION_FAILED', {
          status: 422,
          data: zodError.flatten(),
          cause: error.cause,
        })
      }
    }),
  ],

Thanks for the help!

[dosubot]

Hi @zacharyhansen! I'm Dosu and I’m helping the orpc team.

To include Zod validation errors in your error responses globally in a contract-first orpc + NestJS setup, you’ll want to intercept errors at a central point and reformat them before they’re sent to the client. The recommended pattern is to use an interceptor (like onError) to catch Zod validation errors and attach their details to the error response.

On the server side, orpc’s NestJS integration uses an ImplementInterceptor that handles errors and encodes them using a codec. You can customize this error handling globally by extending or wrapping the interceptor logic, or by using a global error interceptor/hook. The key is to check for Zod errors, then throw a new ORPCError with the flattened Zod error data attached. Here’s a pattern adapted from the official docs and recent PRs:

import { onError, ORPCError } from '@orpc/server';
import { ZodError } from 'zod';

const handler = new OpenAPIHandler(orpcRouter, {
  interceptors: [
    onError((error) => {
      if (
        error instanceof ORPCError &&
        error.cause instanceof ZodError
      ) {
        throw new ORPCError('INPUT_VALIDATION_FAILED', {
          status: 422,
          data: error.cause.flatten(),
          cause: error.cause,
        });
      }
    }),
  ],
});

This approach ensures that whenever a Zod validation error occurs, the client receives a structured error response with the validation issues included in the data field. You can apply this pattern globally at the router or application level for consistent error handling across all endpoints. For NestJS, you may need to adapt this logic into a custom Nest interceptor or middleware, depending on your setup, but the principle is the same: intercept, check for ZodError, and rethrow with details attached.

Recent updates to Zod or orpc shouldn’t affect this pattern, but if you’re using advanced Zod features or custom codecs, double-check that your error handling logic still matches the latest API surface. For more details and examples, see the relevant PR and code patterns.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[zacharyhansen]

@dosu I am using Nestjs as my server so I do not use the OpenAPIHandler

  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter(),
    // see https://orpc.unnoq.com/docs/openapi/nest/implement-contract#body-parser
    { bodyParser: false },
  );

[dosubot]

You can achieve global Zod validation error handling in your NestJS + orpc contract-first setup by adding a custom NestJS Exception Filter or Interceptor. Since you're not using OpenAPIHandler, the onError interceptor pattern from the docs doesn't apply directly, but the principle is the same: catch Zod errors, then rethrow or format them with the details you want.

Here's a pattern you can use:

1. Create a global exception filter (or interceptor) in NestJS that checks for ZodError (or ORPCError wrapping a ZodError).
2. When detected, format the error response to include error.cause.flatten() in the data field and set the status to 422.

Example Exception Filter:

import { ExceptionFilter, Catch, ArgumentsHost, HttpStatus } from '@nestjs/common';
import { Response } from 'express';
import { ZodError } from 'zod';
import { ORPCError } from '@orpc/server';

@Catch()
export class ZodValidationFilter implements ExceptionFilter {
  catch(exception: any, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();

    // Check for ZodError directly or wrapped in ORPCError
    const zodError =
      exception instanceof ZodError
        ? exception
        : exception instanceof ORPCError && exception.cause instanceof ZodError
        ? exception.cause
        : null;

    if (zodError) {
      response.status(422).json({
        defined: false,
        code: 'INPUT_VALIDATION_FAILED',
        status: 422,
        message: 'Input validation failed',
        data: zodError.flatten(),
      });
      return;
    }

    // fallback to default error handling
    response.status(500).json({
      defined: false,
      code: 'INTERNAL_SERVER_ERROR',
      status: 500,
      message: exception.message || 'Internal server error',
    });
  }
}

Then, register this filter globally in your main.ts:

app.useGlobalFilters(new ZodValidationFilter());

This will ensure that any Zod validation errors (even those wrapped in ORPCError) are returned with detailed error info, making debugging much easier. This approach is consistent with orpc's error handling philosophy and works well with contract-first APIs in NestJS. If you want to handle output validation errors as well, you may need to adapt the filter to check for those cases too.

Let me know if you want an Interceptor-based example or have a more complex error pipeline!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[unnoq]

Here how we can catch output validation error with middleware (a middleware require .use before .output to catch ouput validation error by default):

@Controller()
@Injectable()
export class DatasetController {
  constructor(private readonly datasetService: DatasetService) {}

  @Implement(configurationContract.dataset)
  dataset(
    @ClerkContext() clerk_claims: ClerkClaims,
    @AuthorizationContext() authorization: string,
  ) {
   const os = implement(configurationContract).use(onError((error) => {
      // .....
   })

    return {
      byId: os.byId.handler(
        async ({ input }) => {
          const dataset = await this.datasetService.dataset({
            datasetId: input.datasetId,
            organization_id: clerk_claims.organization_id,
            role_name: clerk_claims.o.rol,
          });
          console.log({ dataset: dataset.dataview?.dataview_column });
          return dataset;
        },
      ),

Beside above approach I think we should support interceptors, but I still can't figure out where is the best place to define interceptors in NestJS (PR is welcome - NestJS integration fairly simple)

[unnoq]

If anyone have time, please help me review this (especially about naming conventions, ...) https://github.com/unnoq/orpc/pull/710