{"record":{"id":"56a9a012d5198c56","repo":"mastra-ai/mastra","slug":"agent-step-entryid-cannot-be-stored-structur","errorCode":null,"errorMessage":"Agent step \"${entryId}\" cannot be stored: structuredOutput.schema is not convertible to JSON Schema (${(e as Error).message}).","messagePattern":"Agent step \"(.+?)\" cannot be stored: structuredOutput\\.schema is not convertible to JSON Schema \\((.+?)\\)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/workflows/dynamic/serialize.ts","lineNumber":255,"sourceCode":"  return Object.keys(out).length > 0 ? out : undefined;\n}\n\n/**\n * If the agent-step options carry `structuredOutput.schema`, that schema IS\n * the step's output shape (see `createStepFromAgent`). Emit it as JSON Schema\n * so rehydration can wire the same structured output back in.\n */\nfunction extractStructuredOutputJsonSchema(options: any, entryId: string): Record<string, any> | undefined {\n  const raw = options?.structuredOutput?.schema;\n  if (raw === undefined || raw === null) return undefined;\n  try {\n    // `.agent()`'s typed overload requires a StandardSchemaWithJSON, but the\n    // any-form accepts a raw Zod schema. Normalize either shape here so the\n    // storage form is consistent.\n    const standard = toStandardSchema(raw);\n    return standardSchemaToJSONSchema(standard) as Record<string, any>;\n  } catch (e) {\n    throw new Error(\n      `Agent step \"${entryId}\" cannot be stored: structuredOutput.schema is not convertible to JSON Schema (${(e as Error).message}).`,\n    );\n  }\n}\n","sourceCodeStart":237,"sourceCodeEnd":260,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/dynamic/serialize.ts#L237-L260","documentation":"When an agent step declares `structuredOutput.schema`, the serializer converts that schema to JSON Schema (via `toStandardSchema` + `standardSchemaToJSONSchema`) so it can be stored and rewired on rehydration. If the conversion fails — the schema is a raw Zod schema the converter can't handle, uses unsupported features, or isn't a schema at all — the original conversion error's message is wrapped and rethrown identifying the agent step.","triggerScenarios":"Persisting an agent step whose options include `structuredOutput: { schema: ... }` where the schema fails `toStandardSchema`/`standardSchemaToJSONSchema` conversion: non-schema objects, unsupported Zod constructs (e.g. certain transforms/refs), or an invalid StandardSchemaWithJSON.","commonSituations":"Authors pass a Zod schema with `.transform()`/`.refine()` or complex compositions into `structuredOutput.schema`; works live for validation but the JSON Schema projection fails at persistence time. Also occurs with version mismatches between zod and the converter.","solutions":["Simplify the schema so it's JSON-Schema-representable: move `.transform()`/`.refine()` logic out of `structuredOutput.schema` into a downstream plain step.","Pass a StandardSchemaWithJSON (a schema that already carries JSON Schema metadata) instead of a raw Zod schema.","Check the wrapped inner message (`(${e.message})`) to pinpoint the failing construct.","Upgrade @mastra/core / zod to versions with compatible schema conversion."],"exampleFix":"// before\nagent('myAgent', { structuredOutput: { schema: z.object({ ts: z.date().transform(d => d.toISOString()) }) } })\n\n// after\nagent('myAgent', { structuredOutput: { schema: z.object({ ts: z.string() }) } }) // convert downstream","handlingStrategy":"try-catch","validationCode":"try {\n  if (e.type === 'agent' && e.options?.structuredOutput?.schema != null) {\n    toStandardSchema(e.options.structuredOutput.schema); // probe conversion early\n  }\n} catch (err) { /* schema not storable: fix before persisting */ }","typeGuard":"const hasConvertibleStructuredOutput = (e: StepFlowEntry): boolean =>\n  e.type !== 'agent' || !e.options?.structuredOutput?.schema ||\n  (() => { try { toStandardSchema(e.options.structuredOutput.schema); return true; } catch { return false; } })();","tryCatchPattern":"try {\n  storable = toStorableGraph(stepFlow);\n} catch (e) {\n  if (/structuredOutput\\.schema is not convertible to JSON Schema/.test(e.message)) {\n    // simplify/replace the schema named in the message or drop structuredOutput before saving\n  } else throw e;\n}","preventionTips":["Keep structuredOutput schemas JSON-Schema-representable: no transforms, refinements, or exotic compositions.","Prefer StandardSchemaWithJSON over raw Zod schemas for structuredOutput.schema.","Probe-convert schemas at authoring time, not only at persistence time."],"tags":["workflows","serialization","schema","structured-output"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}