mastra-ai/mastra · error · Error

Agent step "${entryId}" cannot be stored: structuredOutput.s

Error message

Agent step "${entryId}" cannot be stored: structuredOutput.schema is not convertible to JSON Schema (${(e as Error).message}).

What it means

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.

Source

Thrown at packages/core/src/workflows/dynamic/serialize.ts:255

  return Object.keys(out).length > 0 ? out : undefined;
}

/**
 * If the agent-step options carry `structuredOutput.schema`, that schema IS
 * the step's output shape (see `createStepFromAgent`). Emit it as JSON Schema
 * so rehydration can wire the same structured output back in.
 */
function extractStructuredOutputJsonSchema(options: any, entryId: string): Record<string, any> | undefined {
  const raw = options?.structuredOutput?.schema;
  if (raw === undefined || raw === null) return undefined;
  try {
    // `.agent()`'s typed overload requires a StandardSchemaWithJSON, but the
    // any-form accepts a raw Zod schema. Normalize either shape here so the
    // storage form is consistent.
    const standard = toStandardSchema(raw);
    return standardSchemaToJSONSchema(standard) as Record<string, any>;
  } catch (e) {
    throw new Error(
      `Agent step "${entryId}" cannot be stored: structuredOutput.schema is not convertible to JSON Schema (${(e as Error).message}).`,
    );
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Simplify the schema so it's JSON-Schema-representable: move `.transform()`/`.refine()` logic out of `structuredOutput.schema` into a downstream plain step.
2. Pass a StandardSchemaWithJSON (a schema that already carries JSON Schema metadata) instead of a raw Zod schema.
3. Check the wrapped inner message (`(${e.message})`) to pinpoint the failing construct.
4. Upgrade @mastra/core / zod to versions with compatible schema conversion.

Example fix

// before
agent('myAgent', { structuredOutput: { schema: z.object({ ts: z.date().transform(d => d.toISOString()) }) } })

// after
agent('myAgent', { structuredOutput: { schema: z.object({ ts: z.string() }) } }) // convert downstream

try {
  if (e.type === 'agent' && e.options?.structuredOutput?.schema != null) {
    toStandardSchema(e.options.structuredOutput.schema); // probe conversion early
  }
} catch (err) { /* schema not storable: fix before persisting */ }

const hasConvertibleStructuredOutput = (e: StepFlowEntry): boolean =>
  e.type !== 'agent' || !e.options?.structuredOutput?.schema ||
  (() => { try { toStandardSchema(e.options.structuredOutput.schema); return true; } catch { return false; } })();

try {
  storable = toStorableGraph(stepFlow);
} catch (e) {
  if (/structuredOutput\.schema is not convertible to JSON Schema/.test(e.message)) {
    // simplify/replace the schema named in the message or drop structuredOutput before saving
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• STRUCTURED_OUTPUT_PROCESSOR_SCHEMA_REQUIRED
• SleepUntil step "${entry.id}" cannot be stored: dynamic date
• Foreach step cannot iterate a mapping: mappings project data
• Conditional (branch) step cannot be stored: closure predicat
• Loop step "${getSingleStepEntryId(entry.step)}" cannot be st

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