feat(server): expose validation error hook in all server adapters (#13477)

## Description

<!-- Provide a brief description of the changes in this PR -->

Added `onValidationError` hook to customize Zod validation error
responses. When a request fails schema validation (query parameters,
request body, or
path parameters), this hook lets users control the HTTP status code and
response body instead of the hard-coded 400 response with `{ error,
issues }`
format.

The hook can be set at two levels:
- **Server-level** via `ServerConfig.onValidationError` — applies to all
routes
- **Route-level** via `createRoute({ onValidationError })` — overrides
the server-level hook for that route

Supported by all four server adapters: Hono, Express, Fastify, and Koa.

## Related Issue(s)

<!-- Link to the issue(s) this PR addresses, using hashtag notation:
Fixes #123 -->

Fixes #13465

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update

## Checklist

- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added server-level onValidationError hook to customize Zod validation
error responses (status + body).
* Added route-level onValidationError override via createRoute to take
precedence per-route.
* Applies to query, body, and path parameter validation across all
server adapters (Hono, Express, Fastify, Koa).

* **Documentation**
* Docs updated with configuration and route examples showing custom
422/structured error responses and fallback behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: intojhanurag <aojharaj2004@gmail.com>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
Co-authored-by: Roamin <97863888+roaminro@users.noreply.github.com>
Co-authored-by: NikAiyer <nick.aiyer@gmail.com>

Author: 4 people

.changeset/add-validation-error-hook.md

@@ -0,0 +1,28 @@
+---
+'@mastra/core': minor
+'@mastra/server': minor
+'@mastra/hono': minor
+'@mastra/express': minor
+'@mastra/fastify': minor
+'@mastra/koa': minor
+---
+
+Added `onValidationError` hook to `ServerConfig` and `createRoute()`. When a request fails Zod schema validation (query parameters, request body, or path parameters), this hook lets you customize the error response — including the HTTP status code and response body — instead of the default 400 response. Set it on the server config to apply globally, or on individual routes to override per-route. All server adapters (Hono, Express, Fastify, Koa) support this hook.
+
+```ts
+const mastra = new Mastra({
+  server: {
+    onValidationError: (error, context) => ({
+      status: 422,
+      body: {
+        ok: false,
+        errors: error.issues.map(i => ({
+          path: i.path.join('.'),
+          message: i.message,
+        })),
+        source: context,
+      },
+    }),
+  },
+})
+```

docs/src/content/en/reference/configuration.mdx

@@ -726,6 +726,42 @@ export const mastra = new Mastra({
 })
 ```
 
+### server.onValidationError
+
+**Type:** `(error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined`
+
+Custom handler called when a request fails Zod schema validation. Use this to customize validation error responses, change the status code, or format errors to match your API standards.
+
+Return a `{ status, body }` object to override the default `400` response, or `undefined` to fall through to the default behavior. This hook is supported by all server adapters (Hono, Express, Fastify, Koa).
+
+The `context` parameter indicates which part of the request failed validation:
+
+- `'query'` — query parameters
+- `'body'` — request body
+- `'path'` — path parameters
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  server: {
+    onValidationError: (error, context) => ({
+      status: 422,
+      body: {
+        ok: false,
+        errors: error.issues.map(i => ({
+          path: i.path.join('.'),
+          message: i.message,
+        })),
+        source: context,
+      },
+    }),
+  },
+})
+```
+
+You can also set `onValidationError` on individual routes created with `createRoute()`. A route-level hook takes precedence over the server-level hook.
+
 ### server.port
 
 **Type:** `number`\

docs/src/content/en/reference/server/create-route.mdx

@@ -114,6 +114,13 @@ function createRoute<TPath, TQuery, TBody, TResponse, TResponseType>(
     description: 'Mark route as deprecated',
     isOptional: true,
   },
+  {
+    name: 'onValidationError',
+    type: "(error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined",
+    description:
+      'Custom validation error handler for this route. Overrides the server-level `onValidationError` hook. Return `{ status, body }` to customize the response, or `undefined` to use the default.',
+    isOptional: true,
+  },
 ]}
 />
 

packages/core/src/server/index.ts

@@ -5,7 +5,15 @@ import type { Mastra } from '../mastra';
 import type { RequestContext } from '../request-context';
 import type { ApiRoute, MastraAuthConfig, Methods } from './types';
 
-export type { MastraAuthConfig, ContextWithMastra, ApiRoute, HttpLoggingConfig } from './types';
+export type {
+  MastraAuthConfig,
+  ContextWithMastra,
+  ApiRoute,
+  HttpLoggingConfig,
+  ValidationErrorContext,
+  ValidationErrorResponse,
+  ValidationErrorHook,
+} from './types';
 export { MastraAuthProvider } from './auth';
 export type { MastraAuthProviderOptions } from './auth';
 export { CompositeAuth } from './composite-auth';

packages/core/src/server/types.ts

@@ -1,6 +1,7 @@
 import type { Handler, MiddlewareHandler, HonoRequest, Context } from 'hono';
 import type { cors } from 'hono/cors';
 import type { DescribeRouteOptions } from 'hono-openapi';
+import type { ZodError } from 'zod';
 import type { IRBACProvider } from '../auth/ee/interfaces/rbac';
 import type { Mastra } from '../mastra';
 import type { RequestContext } from '../request-context';
@@ -112,6 +113,18 @@ export type HttpLoggingConfig = {
   redactHeaders?: string[];
 };
 
+export type ValidationErrorContext = 'query' | 'body' | 'path';
+
+export type ValidationErrorResponse = {
+  status: number;
+  body: unknown;
+};
+
+export type ValidationErrorHook = (
+  error: ZodError,
+  context: ValidationErrorContext,
+) => ValidationErrorResponse | undefined | void;
+
 export type ServerConfig = {
   /**
    * Port for the server
@@ -283,4 +296,35 @@ export type ServerConfig = {
    * ```
    */
   onError?: (err: Error, c: Context) => Response | Promise<Response>;
+
+  /**
+   * Custom validation error handler for the server. Called when a request fails
+   * Zod schema validation (query parameters, request body, or path parameters).
+   *
+   * Return a `{ status, body }` object to override the default 400 response,
+   * or return `undefined` to fall back to the default behavior.
+   *
+   * @param error - The ZodError from schema validation
+   * @param context - Which part of the request failed: 'query', 'body', or 'path'
+   *
+   * @example
+   * ```ts
+   * const mastra = new Mastra({
+   *   server: {
+   *     onValidationError: (error, context) => ({
+   *       status: 422,
+   *       body: {
+   *         ok: false,
+   *         errors: error.issues.map(i => ({
+   *           path: i.path.join('.'),
+   *           message: i.message,
+   *         })),
+   *         source: context,
+   *       },
+   *     }),
+   *   },
+   * });
+   * ```
+   */
+  onValidationError?: ValidationErrorHook;
 };

packages/server/src/server/server-adapter/index.ts

@@ -2,11 +2,13 @@ import type { ToolsInput } from '@mastra/core/agent';
 import type { Mastra } from '@mastra/core/mastra';
 import { RequestContext } from '@mastra/core/request-context';
 import { MastraServerBase } from '@mastra/core/server';
-import type { ApiRoute, HttpLoggingConfig } from '@mastra/core/server';
+import type { ApiRoute, HttpLoggingConfig, ValidationErrorContext, ValidationErrorResponse } from '@mastra/core/server';
 import { Hono } from 'hono';
+import type { ZodError } from 'zod';
 
 import type { InMemoryTaskStore } from '../a2a/store';
 import { coreAuthMiddleware } from '../auth/helpers';
+import { formatZodError } from '../handlers/error';
 import { normalizeRoutePath } from '../utils';
 import { generateOpenAPIDocument, convertCustomRoutesToOpenAPIPaths } from './openapi-utils';
 import { SERVER_ROUTES, getEffectivePermission } from './routes';
@@ -661,4 +663,36 @@ export abstract class MastraServer<TApp, TRequest, TResponse> extends MastraServ
 
     return bodySchema.parseAsync(body);
   }
+
+  private static readonly CONTEXT_LABELS: Record<ValidationErrorContext, string> = {
+    query: 'query parameters',
+    body: 'request body',
+    path: 'path parameters',
+  };
+
+  protected resolveValidationError(
+    route: ServerRoute,
+    error: ZodError,
+    context: ValidationErrorContext,
+  ): ValidationErrorResponse {
+    const hook = route.onValidationError ?? this.mastra.getServer()?.onValidationError;
+
+    if (hook) {
+      try {
+        const result = hook(error, context);
+        if (result) {
+          return result;
+        }
+      } catch (hookError) {
+        this.mastra.getLogger()?.error('Error in custom onValidationError hook', {
+          error: hookError instanceof Error ? { message: hookError.message, stack: hookError.stack } : hookError,
+        });
+      }
+    }
+
+    return {
+      status: 400,
+      body: formatZodError(error, MastraServer.CONTEXT_LABELS[context]),
+    };
+  }
 }

packages/server/src/server/server-adapter/routes/index.ts

@@ -1,7 +1,7 @@
 import type { Mastra } from '@mastra/core';
 import type { ToolsInput } from '@mastra/core/agent';
 import type { RequestContext } from '@mastra/core/request-context';
-import type { ApiRoute } from '@mastra/core/server';
+import type { ApiRoute, ValidationErrorHook } from '@mastra/core/server';
 import type z from 'zod';
 import type { InMemoryTaskStore } from '../../a2a/store';
 import { A2A_ROUTES } from './a2a';
@@ -107,6 +107,7 @@ export type ServerRoute<
    * requiresPermission: 'workflows:execute'
    */
   requiresPermission?: string;
+  onValidationError?: ValidationErrorHook;
 };
 
 export const SERVER_ROUTES: ServerRoute<any, any, any>[] = [

packages/server/src/server/server-adapter/routes/route-builder.ts

@@ -1,3 +1,4 @@
+import type { ValidationErrorHook } from '@mastra/core/server';
 import { z } from 'zod';
 import type { ZodObject, ZodRawShape, ZodTypeAny } from 'zod';
 import { generateRouteOpenAPI } from '../openapi-utils';
@@ -181,6 +182,7 @@ interface RouteConfig<
    * Uses the format: `resource:action` or `resource:action:resourceId`
    */
   requiresPermission?: string;
+  onValidationError?: ValidationErrorHook;
 }
 
 /**
@@ -255,7 +257,8 @@ export function createRoute<
   TResponseSchema extends z.ZodTypeAny ? z.infer<TResponseSchema> : unknown,
   TResponseType
 > {
-  const { summary, description, tags, deprecated, requiresAuth, requiresPermission, ...baseRoute } = config;
+  const { summary, description, tags, deprecated, requiresAuth, requiresPermission, onValidationError, ...baseRoute } =
+    config;
 
   // Generate OpenAPI specification from the route config
   // Skip OpenAPI generation for 'ALL' method as it doesn't map to OpenAPI
@@ -281,6 +284,7 @@ export function createRoute<
     deprecated,
     requiresAuth,
     requiresPermission,
+    onValidationError,
   };
 }
 

server-adapters/express/src/index.ts

@@ -4,7 +4,6 @@ import type { Mastra } from '@mastra/core/mastra';
 import type { RequestContext } from '@mastra/core/request-context';
 import type { InMemoryTaskStore } from '@mastra/server/a2a/store';
 import { isProtectedCustomRoute } from '@mastra/server/auth';
-import { formatZodError } from '@mastra/server/handlers/error';
 import type { MCPHttpTransportResult, MCPSseTransportResult } from '@mastra/server/handlers/mcp';
 import type { ParsedRequestParams, ServerRoute } from '@mastra/server/server-adapter';
 import {
@@ -430,9 +429,9 @@ export class MastraServer extends MastraServerBase<Application, Request, Respons
             this.mastra.getLogger()?.error('Error parsing query params', {
               error: error instanceof Error ? { message: error.message, stack: error.stack } : error,
             });
-            // Zod validation errors should return 400 Bad Request with structured issues
             if (error instanceof ZodError) {
-              return res.status(400).json(formatZodError(error, 'query parameters'));
+              const { status, body } = this.resolveValidationError(route, error, 'query');
+              return res.status(status).json(body);
             }
             return res.status(400).json({
               error: 'Invalid query parameters',
@@ -448,9 +447,9 @@ export class MastraServer extends MastraServerBase<Application, Request, Respons
             this.mastra.getLogger()?.error('Error parsing body', {
               error: error instanceof Error ? { message: error.message, stack: error.stack } : error,
             });
-            // Zod validation errors should return 400 Bad Request with structured issues
             if (error instanceof ZodError) {
-              return res.status(400).json(formatZodError(error, 'request body'));
+              const { status, body } = this.resolveValidationError(route, error, 'body');
+              return res.status(status).json(body);
             }
             return res.status(400).json({
               error: 'Invalid request body',
@@ -468,7 +467,8 @@ export class MastraServer extends MastraServerBase<Application, Request, Respons
               error: error instanceof Error ? { message: error.message, stack: error.stack } : error,
             });
             if (error instanceof ZodError) {
-              return res.status(400).json(formatZodError(error, 'path parameters'));
+              const { status, body } = this.resolveValidationError(route, error, 'path');
+              return res.status(status).json(body);
             }
             return res.status(400).json({
               error: 'Invalid path parameters',

server-adapters/fastify/src/index.ts

@@ -3,7 +3,6 @@ import type { ToolsInput } from '@mastra/core/agent';
 import type { Mastra } from '@mastra/core/mastra';
 import type { RequestContext } from '@mastra/core/request-context';
 import type { InMemoryTaskStore } from '@mastra/server/a2a/store';
-import { formatZodError } from '@mastra/server/handlers/error';
 import type { MCPHttpTransportResult, MCPSseTransportResult } from '@mastra/server/handlers/mcp';
 import type { ParsedRequestParams, ServerRoute } from '@mastra/server/server-adapter';
 import {
@@ -462,9 +461,9 @@ export class MastraServer extends MastraServerBase<FastifyInstance, FastifyReque
           this.mastra.getLogger()?.error('Error parsing query params', {
             error: error instanceof Error ? { message: error.message, stack: error.stack } : error,
           });
-          // Zod validation errors should return 400 Bad Request with structured issues
           if (error instanceof ZodError) {
-            return reply.status(400).send(formatZodError(error, 'query parameters'));
+            const { status, body } = this.resolveValidationError(route, error, 'query');
+            return reply.status(status).send(body);
           }
           return reply.status(400).send({
             error: 'Invalid query parameters',
@@ -480,9 +479,9 @@ export class MastraServer extends MastraServerBase<FastifyInstance, FastifyReque
           this.mastra.getLogger()?.error('Error parsing body', {
             error: error instanceof Error ? { message: error.message, stack: error.stack } : error,
           });
-          // Zod validation errors should return 400 Bad Request with structured issues
           if (error instanceof ZodError) {
-            return reply.status(400).send(formatZodError(error, 'request body'));
+            const { status, body } = this.resolveValidationError(route, error, 'body');
+            return reply.status(status).send(body);
           }
           return reply.status(400).send({
             error: 'Invalid request body',
@@ -500,7 +499,8 @@ export class MastraServer extends MastraServerBase<FastifyInstance, FastifyReque
             error: error instanceof Error ? { message: error.message, stack: error.stack } : error,
           });
           if (error instanceof ZodError) {
-            return reply.status(400).send(formatZodError(error, 'path parameters'));
+            const { status, body } = this.resolveValidationError(route, error, 'path');
+            return reply.status(status).send(body);
           }
           return reply.status(400).send({
             error: 'Invalid path parameters',