{"record":{"id":"cc356a0915ae483a","repo":"mastra-ai/mastra","slug":"structured-output-options-required","errorCode":"STRUCTURED_OUTPUT_OPTIONS_REQUIRED","errorMessage":"structuredOutput is required to use tryGenerateWithJsonFallback","messagePattern":"structuredOutput is required to use tryGenerateWithJsonFallback","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/utils.ts","lineNumber":45,"sourceCode":"  );\n}\n\nexport async function tryGenerateWithJsonFallback<\n  SCHEMA extends StandardSchemaWithJSON,\n  OUTPUT extends InferStandardSchemaOutput<SCHEMA>,\n>(agent: Agent, prompt: MessageListInput, options: AgentExecutionOptions<OUTPUT>): Promise<FullOutput<OUTPUT>>;\nexport async function tryGenerateWithJsonFallback<OUTPUT extends {}>(\n  agent: Agent,\n  prompt: MessageListInput,\n  options: AgentExecutionOptions<OUTPUT>,\n): Promise<FullOutput<OUTPUT>>;\nexport async function tryGenerateWithJsonFallback<OUTPUT>(\n  agent: Agent,\n  prompt: MessageListInput,\n  options: AgentExecutionOptions<OUTPUT>,\n): Promise<FullOutput<OUTPUT>> {\n  if (!options.structuredOutput?.schema) {\n    throw new MastraError({\n      id: 'STRUCTURED_OUTPUT_OPTIONS_REQUIRED',\n      domain: ErrorDomain.AGENT,\n      category: ErrorCategory.USER,\n      text: 'structuredOutput is required to use tryGenerateWithJsonFallback',\n    });\n  }\n\n  try {\n    const result = await agent.generate(prompt, options);\n    // Some models resolve without throwing but produce no parseable structured\n    // object (empty/malformed JSON). Treat that the same as a thrown error so the\n    // caller still gets the json-prompt-injection retry instead of a downstream\n    // crash when it reads `result.object`. Mirrors tryStreamWithJsonFallback.\n    if (result.object === undefined) {\n      throw new MastraError({\n        id: 'STRUCTURED_OUTPUT_OBJECT_UNDEFINED',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/utils.ts#L27-L63","documentation":"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.","triggerScenarios":"Calling tryGenerateWithJsonFallback directly (or via workflow steps like discoverUnitsStep, routingStep, or the result step) with AgentExecutionOptions lacking options.structuredOutput or options.structuredOutput.schema.","commonSituations":"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.","solutions":["Pass a structuredOutput object with a schema: { structuredOutput: { schema: myZodSchema } }.","Only call tryGenerateWithJsonFallback for structured-generation flows; use agent.generate directly otherwise.","Assert options.structuredOutput?.schema exists at the entry point of your wrapper before delegating."],"exampleFix":"// before\nawait tryGenerateWithJsonFallback(agent, prompt, {});\n// after\nawait tryGenerateWithJsonFallback(agent, prompt, { structuredOutput: { schema: z.object({ answer: z.string() }) } });","handlingStrategy":"validation","validationCode":"if (!options.structuredOutput?.schema) {\n  throw new Error('structuredOutput.schema is required before calling tryGenerateWithJsonFallback');\n}","typeGuard":"function hasStructuredOutput<O>(o: AgentExecutionOptions<O>): o is AgentExecutionOptions<O> & { structuredOutput: { schema: NonNullable<AgentExecutionOptions<O>['structuredOutput']>['schema'] } } {\n  return Boolean(o.structuredOutput?.schema);\n}","tryCatchPattern":"try {\n  return await tryGenerateWithJsonFallback(agent, prompt, options);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'STRUCTURED_OUTPUT_OPTIONS_REQUIRED') {\n    return agent.generate(prompt, options); // non-structured path\n  }\n  throw e;\n}","preventionTips":["Always attach structuredOutput.schema when using JSON-fallback helpers","Build options via typed factory functions that require the schema","Only invoke fallback helpers from structured-generation flows"],"tags":["structured-output","agent","missing-argument","zod"],"backgroundTag":"structured-output-not-configured","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}