fix(core): use value-based null detection in validateToolInput instead of error message matching (#14496)

Co-authored-by: caizongding.1 <caizongding.1@jd.com>
Co-authored-by: Grayson Hicks <graysonhicks@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>

Author: 5 people

.changeset/happy-clowns-change.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Fixed null detection in tool input validation to check actual values at failing paths instead of relying on error message string matching. This ensures null values from LLMs are correctly handled even when validators produce error messages that don't contain the word "null" (e.g., "must be string"). Fixes #14476.

packages/core/src/tools/validation.test.ts

@@ -1495,6 +1495,122 @@ describe('validateToolInput - Absent Optional Fields in Nested Objects (GitHub #
   });
 });
 
+describe('validateToolInput - Value-Based Null Detection (GitHub #14476)', () => {
+  // These tests verify the fix for https://github.com/mastra-ai/mastra/issues/14476
+  // The null detection in Step 5 should check the actual value at the failing path
+  // rather than relying on error message string matching (e.g., checking for 'null'
+  // in the message). This ensures null values are detected even when validators
+  // return messages like "must be string" or "must be object".
+
+  it('should detect null values even when error message does not contain "null"', () => {
+    // Use a custom refinement whose error message deliberately avoids "null".
+    // This simulates non-Zod Standard Schema validators (e.g. JSON Schema)
+    // that report errors like "must be string" instead of "received null".
+    const schema = z.object({
+      name: z.string(),
+      description: z
+        .string()
+        .optional()
+        .superRefine((val, ctx) => {
+          if (typeof val !== 'string' && val !== undefined) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'must be a valid string value' });
+          }
+        }),
+      tags: z
+        .array(z.string())
+        .optional()
+        .superRefine((val, ctx) => {
+          if (!Array.isArray(val) && val !== undefined) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'expected an array of strings' });
+          }
+        }),
+    });
+
+    // LLM sends null for optional fields — error messages won't contain "null"
+    const input = { name: 'test', description: null, tags: null };
+
+    const result = validateToolInput(schema, input);
+
+    expect(result.error).toBeUndefined();
+    expect(result.data).toEqual({ name: 'test' });
+  });
+
+  it('should handle null in nested optional fields with non-null error messages', () => {
+    // Custom refinements that produce errors without "null" in the message
+    const schema = z.object({
+      config: z.object({
+        timeout: z
+          .number()
+          .optional()
+          .superRefine((val, ctx) => {
+            if (typeof val !== 'number' && val !== undefined) {
+              ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'must be a numeric value' });
+            }
+          }),
+        retries: z
+          .number()
+          .optional()
+          .superRefine((val, ctx) => {
+            if (typeof val !== 'number' && val !== undefined) {
+              ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'must be a numeric value' });
+            }
+          }),
+        label: z
+          .string()
+          .optional()
+          .superRefine((val, ctx) => {
+            if (typeof val !== 'string' && val !== undefined) {
+              ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'must be a valid string value' });
+            }
+          }),
+      }),
+    });
+
+    const input = {
+      config: {
+        timeout: null,
+        retries: null,
+        label: null,
+      },
+    };
+
+    const result = validateToolInput(schema, input);
+
+    expect(result.error).toBeUndefined();
+    expect(result.data).toEqual({ config: {} });
+  });
+
+  it('should still preserve null for .nullable() fields', () => {
+    const schema = z.object({
+      name: z.string(),
+      deletedAt: z.string().nullable(),
+      note: z.string().optional(),
+    });
+
+    const input = { name: 'test', deletedAt: null, note: null };
+
+    const result = validateToolInput(schema, input);
+
+    expect(result.error).toBeUndefined();
+    expect(result.data).toEqual({ name: 'test', deletedAt: null });
+  });
+
+  it('should not misidentify non-null values at failing paths as null-related', () => {
+    const schema = z.object({
+      count: z.number(),
+      name: z.string(),
+    });
+
+    // Invalid types but not null - these should NOT be treated as null-related
+    const input = { count: 'not-a-number', name: 123 };
+
+    const result = validateToolInput(schema, input);
+
+    // Should still fail validation (can't fix by stripping)
+    expect(result.error).toBeDefined();
+  });
+});
+
 describe('validateToolInput - Undefined to Null Conversion (GitHub #11457)', () => {
   // These tests verify the fix for https://github.com/mastra-ai/mastra/issues/11457
   // When schemas are processed through OpenAI compat layers, .optional() is converted

packages/core/src/tools/validation.ts

@@ -322,6 +322,28 @@ function stripNullishValuesAtPaths(input: unknown, paths: Set<string>, currentPa
   return result;
 }
 
+/**
+ * Gets the value at a path in a nested object, using the same path segment format
+ * as Standard Schema validation issues.
+ *
+ * @param obj The object to traverse
+ * @param pathSegments Array of path segments from a validation issue
+ * @returns The value at the path, or a sentinel symbol if the path doesn't exist
+ */
+const PATH_NOT_FOUND = Symbol('PATH_NOT_FOUND');
+function getValueAtPath(obj: unknown, pathSegments: ReadonlyArray<PropertyKey | { key: PropertyKey }>): unknown {
+  let current: unknown = obj;
+  for (const segment of pathSegments) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return PATH_NOT_FOUND;
+    }
+    const key =
+      typeof segment === 'object' && segment !== null && 'key' in segment ? String(segment.key) : String(segment);
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
 /**
  * Coerces stringified JSON values in object properties when the schema expects
  * an array or object but the LLM returned a JSON string.
@@ -468,9 +490,18 @@ export function validateToolInput<T = unknown>(
   // LLMs like Gemini send null for optional fields, but Zod's .optional() only
   // accepts undefined, not null. We only strip nulls for fields that caused
   // validation errors, preserving null for .nullable() schemas that need it.
+  //
+  // We detect null-related failures by checking the actual value at the failing
+  // path rather than relying on error message string matching (GitHub #14476).
+  // This ensures we catch null values regardless of the validator's error message
+  // format (e.g., "must be string", "must be object", etc.).
   const failingNullPaths = new Set(
     validation.issues
-      .filter(issue => issue.message?.includes('null'))
+      .filter(issue => {
+        if (!issue.path || issue.path.length === 0) return false;
+        const value = getValueAtPath(normalizedInput, issue.path);
+        return value === null || value === undefined;
+      })
       .map(issue => issue.path?.map(p => (typeof p === 'object' && 'key' in p ? String(p.key) : String(p))).join('.'))
       .filter((p): p is string => !!p),
   );