mastra-ai/mastra · error · MastraError

STRUCTURED_OUTPUT_OPTIONS_REQUIRED

STRUCTURED_OUTPUT_OPTIONS_REQUIRED

Error message

structuredOutput is required to use tryGenerateWithJsonFallback

What it means

tryGenerateWithJsonFallback() is the JSON-fallback retry path for structured generation and requires options.structuredOutput.schema to be set. It throws MastraError STRUCTURED_OUTPUT_OPTIONS_REQUIRED (USER category) when called without a structuredOutput schema, since there would be nothing to validate or fall back to.

Source

Thrown at packages/core/src/agent/utils.ts:45

  );
}

export async function tryGenerateWithJsonFallback<
  SCHEMA extends StandardSchemaWithJSON,
  OUTPUT extends InferStandardSchemaOutput<SCHEMA>,
>(agent: Agent, prompt: MessageListInput, options: AgentExecutionOptions<OUTPUT>): Promise<FullOutput<OUTPUT>>;
export async function tryGenerateWithJsonFallback<OUTPUT extends {}>(
  agent: Agent,
  prompt: MessageListInput,
  options: AgentExecutionOptions<OUTPUT>,
): Promise<FullOutput<OUTPUT>>;
export async function tryGenerateWithJsonFallback<OUTPUT>(
  agent: Agent,
  prompt: MessageListInput,
  options: AgentExecutionOptions<OUTPUT>,
): Promise<FullOutput<OUTPUT>> {
  if (!options.structuredOutput?.schema) {
    throw new MastraError({
      id: 'STRUCTURED_OUTPUT_OPTIONS_REQUIRED',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      text: 'structuredOutput is required to use tryGenerateWithJsonFallback',
    });
  }

  try {
    const result = await agent.generate(prompt, options);
    // Some models resolve without throwing but produce no parseable structured
    // object (empty/malformed JSON). Treat that the same as a thrown error so the
    // caller still gets the json-prompt-injection retry instead of a downstream
    // crash when it reads `result.object`. Mirrors tryStreamWithJsonFallback.
    if (result.object === undefined) {
      throw new MastraError({
        id: 'STRUCTURED_OUTPUT_OBJECT_UNDEFINED',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a structuredOutput object with a schema: { structuredOutput: { schema: myZodSchema } }.
2. Only call tryGenerateWithJsonFallback for structured-generation flows; use agent.generate directly otherwise.
3. Assert options.structuredOutput?.schema exists at the entry point of your wrapper before delegating.

Example fix

// before
await tryGenerateWithJsonFallback(agent, prompt, {});
// after
await tryGenerateWithJsonFallback(agent, prompt, { structuredOutput: { schema: z.object({ answer: z.string() }) } });

if (!options.structuredOutput?.schema) {
  throw new Error('structuredOutput.schema is required before calling tryGenerateWithJsonFallback');
}

function hasStructuredOutput<O>(o: AgentExecutionOptions<O>): o is AgentExecutionOptions<O> & { structuredOutput: { schema: NonNullable<AgentExecutionOptions<O>['structuredOutput']>['schema'] } } {
  return Boolean(o.structuredOutput?.schema);
}

try {
  return await tryGenerateWithJsonFallback(agent, prompt, options);
} catch (e) {
  if (e instanceof MastraError && e.id === 'STRUCTURED_OUTPUT_OPTIONS_REQUIRED') {
    return agent.generate(prompt, options); // non-structured path
  }
  throw e;
}

When it happens

Trigger: Calling tryGenerateWithJsonFallback directly (or via workflow steps like discoverUnitsStep, routingStep, or the result step) with AgentExecutionOptions lacking options.structuredOutput or options.structuredOutput.schema.

Common situations: Wiring a custom generation pipeline and forgetting to forward structuredOutput options; conditionally building options objects where the structuredOutput branch was skipped; internal workflow steps invoked with generate options from a non-structured call site.

Related errors

• No result received from agent execution on iteration ${itera
• AGENT_GENERATE_LEGACY_STRUCTURED_OUTPUT_NOT_SUPPORTED
• AGENT_REQUEST_CONTEXT_VALIDATION_FAILED
• AGENT_SEND_STREAM_RESUME_MISSING_TARGET
• resourceId and threadId are required to queue a message

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