mastra-ai/mastra · error

[Schema Builder] Failed to convert schema parameters to Zod.

Error message

[Schema Builder] Failed to convert schema parameters to Zod. Original schema: ${JSON.stringify(jsonSchemaToConvert)}\n${e.stack}

What it means

convertSchemaToZod() attempts to convert a JSON Schema / AI SDK Schema into a Zod schema (via convertJsonSchemaToZod v4 or v3). If that conversion throws for any reason (unsupported keywords, malformed JSON Schema, library bug), the catch block logs the original schema and rethrows a wrapped Error containing the original schema JSON and the inner stack trace, prefixed with '[Schema Builder]'.

Source

Thrown at packages/schema-compat/src/utils.ts:114

 * ```
 */
export function convertSchemaToZod(schema: Schema | ZodSchema | JSONSchema7): ZodType {
  if (isZodType(schema)) {
    return schema;
  } else {
    const jsonSchemaToConvert = 'jsonSchema' in schema ? schema.jsonSchema : schema;
    try {
      if ('toJSONSchema' in z) {
        // @ts-expect-error - type issue in convertJsonSchemaToZod
        return convertJsonSchemaToZod(jsonSchemaToConvert);
      } else {
        // @ts-expect-error - type issue in convertJsonSchemaToZodV3
        return convertJsonSchemaToZodV3(jsonSchemaToConvert);
      }
    } catch (e: unknown) {
      const errorMessage = `[Schema Builder] Failed to convert schema parameters to Zod. Original schema: ${JSON.stringify(jsonSchemaToConvert)}`;
      console.error(errorMessage, e);
      throw new Error(errorMessage + (e instanceof Error ? `\n${e.stack}` : '\nUnknown error object'));
    }
  }
}

/**
 * Processes a schema using provider compatibility layers and converts it to an AI SDK Schema.
 *
 * @param options - Configuration object for schema processing
 * @param options.schema - The schema to process (AI SDK Schema or Zod object schema)
 * @param options.compatLayers - Array of compatibility layers to try
 * @param options.mode - Must be 'aiSdkSchema'
 * @returns Processed schema as an AI SDK Schema
 */
export function applyCompatLayer(options: {
  schema: PublicSchema<any>;
  compatLayers: SchemaCompatLayer[];
  mode: 'aiSdkSchema';
}): Schema;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the embedded inner stack trace and original schema JSON in the message to find the offending keyword/value.
2. Simplify or rewrite the unsupported part of the JSON Schema (replace oneOf/anyOf combos with simpler structures where possible).
3. Pass a native Zod schema instead of JSON Schema to sidestep conversion entirely.
4. Fix typos/invalid values in the schema (validate it with a JSON Schema validator such as ajv first).
5. If caused by a converter limitation, file an issue with the 'Original schema' payload included in the message.

Example fix

// before
schema: { type: 'strng', properties: { q: { type: 'string' } } } // typo breaks converter
// after
schema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] }

import Ajv from 'ajv';
const ajv = new Ajv();
function isWellFormedJsonSchema(s: unknown): boolean {
  try { ajv.compile(s as object); return true; } catch { return false; }
}
// call isWellFormedJsonSchema(myJsonSchema) before convertSchemaToZod

const isJsonObjectSchema = (s: unknown): s is { type: string; properties?: Record<string, unknown> } =>
  typeof s === 'object' && s !== null && 'type' in s;

let zodSchema;
try {
  zodSchema = convertSchemaToZod(jsonSchema);
} catch (e) {
  console.error('Schema conversion failed for:', jsonSchema);
  zodSchema = z.object({}); // or rethrow with your own context
}

When it happens

Trigger: Calling convertSchemaToZod (via requestContextSchema/result/applyCompatLayer) with a JSON Schema that the converter cannot handle: exotic/unsupported keywords ($ref chains, oneOf with complex branches), malformed schema, or null/undefined internals.

Common situations: Schemas generated by external tools (OpenAPI generators, swagger-to-jsonschema) containing unsupported constructs; hand-written JSON Schema with typos ('type': 'strng'); deeply nested or recursive schemas; version drift between zod v3 and v4 converters.

Related errors

• We could not convert the schema to a JSONSchema
• SchemaValidationError(field, this.formatErrors(result.error)
• Schema validation failed due to an invalid schema definition
• ${message}
• WORKFLOW_SCHEMA_VALIDATION_FAILED

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/e5ff813e560ce753. Report an issue: GitHub.