fix(server): allow omitted optional memory query params (#15969)

This fixes a memory query validation regression that shows up when the
runtime resolves Zod 4.4.0 or newer. Zod 4.4.0 tightened
missing-key/undefined behavior for object properties, which is called
out in the release notes:
https://github.com/colinhacks/zod/releases/tag/v4.4.0

Our memory schemas were expressing optional preprocessed query fields as
`z.preprocess(fn, inner.optional())`. With newer Zod, omitted params
like `orderBy`, `metadata`, `include`, `filter`, and
`includeSystemReminders` can then fail with `expected nonoptional,
received undefined`, which breaks memory thread/message loading in
Studio and the underlying API routes.

This changes those fields to the safer equivalent `z.preprocess(fn,
inner).optional()` and keeps the preprocess functions passing through
`undefined`. That preserves the intended behavior: omitted query params
stay optional, but present JSON values still get parsed and validated.

Before:
```ts
z.preprocess(fn, inner.optional())
```

After:
```ts
z.preprocess(fn, inner).optional()
```

I also added regression coverage for the exact omitted-parameter cases
on `listThreadsQuerySchema` and `listMessagesQuerySchema`.

I verified this in the `apr-30` demo by linking the local
`@mastra/server` package and hitting the same routes that were
previously 400ing. After the change, both `/api/memory/threads` and
`/api/memory/threads/:threadId/messages` return normal JSON again
instead of validation errors.

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

## ELI5 (Explain Like I'm 5)

When you ask an API for information without providing some optional
details, the server was incorrectly rejecting your request as invalid
(because of a newer version of the validation tool it uses). This PR
fixes that by reorganizing how the validation rules work so that
optional details are actually treated as optional—if you don't send
them, that's perfectly fine.

## Changes Overview

This PR fixes a validation regression in the memory query API endpoints
that was introduced by Zod 4.4.0+. The issue occurred when optional
query parameters were omitted from requests to `/api/memory/threads` and
`/api/memory/threads/:threadId/messages`, causing validation errors with
"expected nonoptional, received undefined" even though those parameters
were intended to be optional.

## Root Cause

The memory query schemas were using `z.preprocess(fn,
schema.optional())`, which caused Zod 4.4.0+ to reject `undefined`
values during the preprocessing step. The stricter validation in newer
Zod versions exposed this improper ordering of the optional modifier,
preventing the preprocessor from handling undefined values before the
optional check.

## Solution

Refactored multiple Zod query schemas to move optionality outside the
preprocess call, changing from `z.preprocess(fn, schema.optional())` to
`z.preprocess(fn, schema).optional()`. This ensures that:
- Omitted query parameters (orderBy, metadata, include, filter,
includeSystemReminders, resourceId) pass through preprocessing without
triggering validation errors, and remain `undefined` in the parsed
result
- Present JSON values are still properly parsed and validated through
the preprocess functions
- The intended optional behavior is preserved for backward compatibility

## Files Modified

- **packages/server/src/server/schemas/memory.ts**: Refactored
preprocess callbacks in `storageOrderBySchema`, `messageOrderBySchema`,
`includeSchema`, `filterSchema`, `memoryConfigSchema`, and related
metadata/system reminder fields to use the corrected pattern (+122/-103
lines)
- **packages/server/src/server/schemas/memory.test.ts**: Added
regression tests verifying that `listThreadsQuerySchema` and
`listMessagesQuerySchema` successfully parse when optional query
parameters are omitted, with those parameters remaining `undefined` in
the result (+28 lines)
- **.changeset/four-owls-flow.md**: Patch-level version bump for
@mastra/server (+5 lines)

## Testing & Verification

- Added regression test coverage confirming that omitted optional
parameters (`resourceId`, `orderBy`, `metadata`, `include`, `filter`)
don't cause validation errors and correctly resolve to `undefined`
- Verified locally by linking the @mastra/server package and confirming
`/api/memory/threads` and `/api/memory/threads/:threadId/messages`
return normal JSON responses instead of 400 validation errors

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: Ehindero Israel

.changeset/four-owls-flow.md

@@ -0,0 +1,5 @@
+---
+'@mastra/server': patch
+---
+
+Fixed memory query validation when optional JSON query params are omitted with newer Zod versions.

packages/server/src/server/schemas/memory.test.ts

@@ -14,6 +14,21 @@ import { listMessagesQuerySchema, listThreadsQuerySchema } from './memory';
  */
 describe('Memory Schema Query Parsing', () => {
   describe('listMessagesQuerySchema', () => {
+    it('should allow omitted optional query params', () => {
+      const result = listMessagesQuerySchema.safeParse({
+        page: 0,
+        perPage: 20,
+      });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.orderBy).toBeUndefined();
+        expect(result.data.include).toBeUndefined();
+        expect(result.data.filter).toBeUndefined();
+        expect(result.data.includeSystemReminders).toBeUndefined();
+      }
+    });
+
     describe('orderBy parameter parsing', () => {
       it('should parse orderBy when passed as an object', () => {
         const result = listMessagesQuerySchema.safeParse({
@@ -251,6 +266,19 @@ describe('Memory Schema Query Parsing', () => {
   });
 
   describe('listThreadsQuerySchema', () => {
+    it('should allow omitted optional query params', () => {
+      const result = listThreadsQuerySchema.safeParse({
+        page: 0,
+        perPage: 100,
+      });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.metadata).toBeUndefined();
+        expect(result.data.orderBy).toBeUndefined();
+      }
+    });
+
     describe('orderBy parameter parsing', () => {
       it('should parse orderBy when passed as an object', () => {
         const result = listThreadsQuerySchema.safeParse({

packages/server/src/server/schemas/memory.ts

@@ -25,92 +25,96 @@ export const optionalAgentIdQuerySchema = z.object({
  * Storage order by configuration for threads and agents (have both createdAt and updatedAt)
  * Handles JSON parsing from query strings
  */
-const storageOrderBySchema = z.preprocess(
-  val => {
-    if (typeof val === 'string') {
-      try {
-        return JSON.parse(val);
-      } catch {
-        return undefined;
+const storageOrderBySchema = z
+  .preprocess(
+    val => {
+      if (val === undefined) return val;
+      if (typeof val === 'string') {
+        try {
+          return JSON.parse(val);
+        } catch {
+          return undefined;
+        }
       }
-    }
-    return val;
-  },
-  z
-    .object({
+      return val;
+    },
+    z.object({
       field: z.enum(['createdAt', 'updatedAt']).optional(),
       direction: z.enum(['ASC', 'DESC']).optional(),
-    })
-    .optional(),
-);
+    }),
+  )
+  .optional();
 
 /**
  * Storage order by configuration for messages (only have createdAt)
  * Handles JSON parsing from query strings
  */
-const messageOrderBySchema = z.preprocess(
-  val => {
-    if (typeof val === 'string') {
-      try {
-        return JSON.parse(val);
-      } catch {
-        return undefined;
+const messageOrderBySchema = z
+  .preprocess(
+    val => {
+      if (val === undefined) return val;
+      if (typeof val === 'string') {
+        try {
+          return JSON.parse(val);
+        } catch {
+          return undefined;
+        }
       }
-    }
-    return val;
-  },
-  z
-    .object({
+      return val;
+    },
+    z.object({
       field: z.enum(['createdAt']).optional(),
       direction: z.enum(['ASC', 'DESC']).optional(),
-    })
-    .optional(),
-);
+    }),
+  )
+  .optional();
 
 /**
  * Include schema for message listing - handles JSON parsing from query strings
  */
-const includeSchema = z.preprocess(
-  val => {
-    if (typeof val === 'string') {
-      try {
-        return JSON.parse(val);
-      } catch {
-        // Return invalid string to fail validation (z.array will reject string type)
-        return val;
+const includeSchema = z
+  .preprocess(
+    val => {
+      if (val === undefined) return val;
+      if (typeof val === 'string') {
+        try {
+          return JSON.parse(val);
+        } catch {
+          // Return invalid string to fail validation (z.array will reject string type)
+          return val;
+        }
       }
-    }
-    return val;
-  },
-  z
-    .array(
+      return val;
+    },
+    z.array(
       z.object({
         id: z.string(),
         threadId: z.string().optional(),
         withPreviousMessages: z.number().optional(),
         withNextMessages: z.number().optional(),
       }),
-    )
-    .optional(),
-);
+    ),
+  )
+  .optional();
 
 /**
  * Filter schema for message listing - handles JSON parsing from query strings
  */
-const filterSchema = z.preprocess(
-  val => {
-    if (typeof val === 'string') {
-      try {
-        return JSON.parse(val);
-      } catch {
-        // Return invalid string to fail validation (z.object will reject string type)
-        return val;
+const filterSchema = z
+  .preprocess(
+    val => {
+      if (val === undefined) return val;
+      if (typeof val === 'string') {
+        try {
+          return JSON.parse(val);
+        } catch {
+          // Return invalid string to fail validation (z.object will reject string type)
+          return val;
+        }
       }
-    }
-    return val;
-  },
-  z
-    .object({
+      return val;
+    },
+    z.object({
       dateRange: z
         .object({
           start: z.coerce.date().optional(),
@@ -120,24 +124,30 @@ const filterSchema = z.preprocess(
         })
         .optional(),
       roles: z.array(z.string()).optional(),
-    })
-    .optional(),
-);
+    }),
+  )
+  .optional();
 
 /**
  * Memory config schema - handles JSON parsing from query strings
  */
-const memoryConfigSchema = z.preprocess(val => {
-  if (typeof val === 'string') {
-    try {
-      return JSON.parse(val);
-    } catch {
-      // Return invalid string to fail validation (z.record will reject string type)
+const memoryConfigSchema = z
+  .preprocess(
+    val => {
+      if (val === undefined) return val;
+      if (typeof val === 'string') {
+        try {
+          return JSON.parse(val);
+        } catch {
+          // Return invalid string to fail validation (z.record will reject string type)
+          return val;
+        }
+      }
       return val;
-    }
-  }
-  return val;
-}, z.record(z.string(), z.unknown()).optional());
+    },
+    z.record(z.string(), z.unknown()),
+  )
+  .optional();
 
 /**
  * Thread object structure
@@ -190,20 +200,23 @@ export const getMemoryConfigQuerySchema = agentIdQuerySchema;
 export const listThreadsQuerySchema = createPagePaginationSchema(100).extend({
   agentId: z.string().optional(),
   resourceId: z.string().optional(),
-  metadata: z.preprocess(
-    val => {
-      if (typeof val === 'string') {
-        try {
-          return JSON.parse(val);
-        } catch {
-          // Return invalid string to fail validation (z.record will reject string type)
-          return val;
+  metadata: z
+    .preprocess(
+      val => {
+        if (val === undefined) return val;
+        if (typeof val === 'string') {
+          try {
+            return JSON.parse(val);
+          } catch {
+            // Return invalid string to fail validation (z.record will reject string type)
+            return val;
+          }
         }
-      }
-      return val;
-    },
-    z.optional(z.record(z.string(), z.any())),
-  ),
+        return val;
+      },
+      z.record(z.string(), z.any()),
+    )
+    .optional(),
   orderBy: storageOrderBySchema,
 });
 
@@ -226,11 +239,14 @@ export const listMessagesQuerySchema = createPagePaginationSchema(40).extend({
   orderBy: messageOrderBySchema,
   include: includeSchema,
   filter: filterSchema,
-  includeSystemReminders: z.preprocess(val => {
-    if (val === 'true') return true;
-    if (val === 'false') return false;
-    return val;
-  }, z.boolean().optional()),
+  includeSystemReminders: z
+    .preprocess(val => {
+      if (val === undefined) return val;
+      if (val === 'true') return true;
+      if (val === 'false') return false;
+      return val;
+    }, z.boolean())
+    .optional(),
 });
 
 /**
@@ -278,20 +294,23 @@ export const getMemoryStatusNetworkQuerySchema = agentIdQuerySchema;
 export const listThreadsNetworkQuerySchema = createPagePaginationSchema(100).extend({
   agentId: z.string().optional(),
   resourceId: z.string().optional(),
-  metadata: z.preprocess(
-    val => {
-      if (typeof val === 'string') {
-        try {
-          return JSON.parse(val);
-        } catch {
-          // Return invalid string to fail validation (z.record will reject string type)
-          return val;
+  metadata: z
+    .preprocess(
+      val => {
+        if (val === undefined) return val;
+        if (typeof val === 'string') {
+          try {
+            return JSON.parse(val);
+          } catch {
+            // Return invalid string to fail validation (z.record will reject string type)
+            return val;
+          }
         }
-      }
-      return val;
-    },
-    z.optional(z.record(z.string(), z.any())),
-  ),
+        return val;
+      },
+      z.record(z.string(), z.any()),
+    )
+    .optional(),
   orderBy: storageOrderBySchema,
 });