{"record":{"id":"e5ff813e560ce753","repo":"mastra-ai/mastra","slug":"schema-builder-failed-to-convert-schema-paramete","errorCode":null,"errorMessage":"[Schema Builder] Failed to convert schema parameters to Zod. Original schema: ${JSON.stringify(jsonSchemaToConvert)}\\n${e.stack}","messagePattern":"\\[Schema Builder\\] Failed to convert schema parameters to Zod\\. Original schema: (.+?)\\\\n(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/schema-compat/src/utils.ts","lineNumber":114,"sourceCode":" * ```\n */\nexport function convertSchemaToZod(schema: Schema | ZodSchema | JSONSchema7): ZodType {\n  if (isZodType(schema)) {\n    return schema;\n  } else {\n    const jsonSchemaToConvert = 'jsonSchema' in schema ? schema.jsonSchema : schema;\n    try {\n      if ('toJSONSchema' in z) {\n        // @ts-expect-error - type issue in convertJsonSchemaToZod\n        return convertJsonSchemaToZod(jsonSchemaToConvert);\n      } else {\n        // @ts-expect-error - type issue in convertJsonSchemaToZodV3\n        return convertJsonSchemaToZodV3(jsonSchemaToConvert);\n      }\n    } catch (e: unknown) {\n      const errorMessage = `[Schema Builder] Failed to convert schema parameters to Zod. Original schema: ${JSON.stringify(jsonSchemaToConvert)}`;\n      console.error(errorMessage, e);\n      throw new Error(errorMessage + (e instanceof Error ? `\\n${e.stack}` : '\\nUnknown error object'));\n    }\n  }\n}\n\n/**\n * Processes a schema using provider compatibility layers and converts it to an AI SDK Schema.\n *\n * @param options - Configuration object for schema processing\n * @param options.schema - The schema to process (AI SDK Schema or Zod object schema)\n * @param options.compatLayers - Array of compatibility layers to try\n * @param options.mode - Must be 'aiSdkSchema'\n * @returns Processed schema as an AI SDK Schema\n */\nexport function applyCompatLayer(options: {\n  schema: PublicSchema<any>;\n  compatLayers: SchemaCompatLayer[];\n  mode: 'aiSdkSchema';\n}): Schema;","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/schema-compat/src/utils.ts#L96-L132","documentation":"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]'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the embedded inner stack trace and original schema JSON in the message to find the offending keyword/value.","Simplify or rewrite the unsupported part of the JSON Schema (replace oneOf/anyOf combos with simpler structures where possible).","Pass a native Zod schema instead of JSON Schema to sidestep conversion entirely.","Fix typos/invalid values in the schema (validate it with a JSON Schema validator such as ajv first).","If caused by a converter limitation, file an issue with the 'Original schema' payload included in the message."],"exampleFix":"// before\nschema: { type: 'strng', properties: { q: { type: 'string' } } } // typo breaks converter\n// after\nschema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] }","handlingStrategy":"validation","validationCode":"import Ajv from 'ajv';\nconst ajv = new Ajv();\nfunction isWellFormedJsonSchema(s: unknown): boolean {\n  try { ajv.compile(s as object); return true; } catch { return false; }\n}\n// call isWellFormedJsonSchema(myJsonSchema) before convertSchemaToZod","typeGuard":"const isJsonObjectSchema = (s: unknown): s is { type: string; properties?: Record<string, unknown> } =>\n  typeof s === 'object' && s !== null && 'type' in s;","tryCatchPattern":"let zodSchema;\ntry {\n  zodSchema = convertSchemaToZod(jsonSchema);\n} catch (e) {\n  console.error('Schema conversion failed for:', jsonSchema);\n  zodSchema = z.object({}); // or rethrow with your own context\n}","preventionTips":["Validate JSON Schemas with ajv (or similar) before handing them to converters.","Avoid exotic keywords (complex $ref, if/then chains) in tool parameter schemas.","Prefer authoring schemas in Zod directly instead of raw JSON Schema.","Keep zod and schema-compat versions in sync."],"tags":["schema","json-schema","zod","conversion"],"backgroundTag":"schema-conversion-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}