{"record":{"id":"e31cd1c790eaebb2","repo":"mastra-ai/mastra","slug":"structured-output-processor-schema-required","errorCode":"STRUCTURED_OUTPUT_PROCESSOR_SCHEMA_REQUIRED","errorMessage":"StructuredOutputProcessor requires a schema to be provided","messagePattern":"StructuredOutputProcessor requires a schema to be provided","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/processors/processors/structured-output.ts","lineNumber":54,"sourceCode":"  readonly id = STRUCTURED_OUTPUT_PROCESSOR_NAME;\n  readonly name = 'Structured Output';\n\n  public schema: StandardSchemaWithJSON<OUTPUT>;\n  private structuringAgent: Agent<any, any, undefined>;\n  private structuringModel: MastraModelConfig;\n  private structuringInstructions: string;\n  private agent?: Agent<any, any, any>;\n  private useAgent = false;\n  private errorStrategy: 'strict' | 'warn' | 'fallback';\n  private fallbackValue?: OUTPUT;\n  private isStructuringAgentStreamStarted = false;\n  private jsonPromptInjection?: boolean | 'system' | 'inline' | 'auto';\n  private providerOptions?: ProviderOptions;\n  private logger?: IMastraLogger;\n\n  constructor(options: StructuredOutputOptions<OUTPUT>) {\n    if (!options.schema) {\n      throw new MastraError({\n        id: 'STRUCTURED_OUTPUT_PROCESSOR_SCHEMA_REQUIRED',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text: 'StructuredOutputProcessor requires a schema to be provided',\n      });\n    }\n    if (!options.model) {\n      throw new MastraError({\n        id: 'STRUCTURED_OUTPUT_PROCESSOR_MODEL_REQUIRED',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text: 'StructuredOutputProcessor requires a model to be provided either in options or as fallback',\n      });\n    }\n\n    this.schema = options.schema;\n    this.structuringModel = options.model;\n    this.useAgent = options.useAgent ?? false;","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/processors/processors/structured-output.ts#L36-L72","documentation":"StructuredOutputProcessor uses a Zod/standard schema to constrain the model's output into a typed object. The schema is mandatory — without it the processor cannot build the output instruction or validate results — so the constructor throws a MastraError (id STRUCTURED_OUTPUT_PROCESSOR_SCHEMA_REQUIRED, domain AGENT, category USER) when `options.schema` is falsy.","triggerScenarios":"Calling `new StructuredOutputProcessor({})`, passing `schema: undefined` (e.g. a variable holding the schema was never assigned), or constructing with an object where the schema key is misspelled (`schemas`, `zodSchema`).","commonSituations":"Dynamically loading a schema module that failed to export, conditionally defining schemas and a branch leaves it undefined, migrating from older processor APIs where the schema was optional or named differently.","solutions":["Pass a schema: `new StructuredOutputProcessor({ schema: z.object({ ... }) })`.","Check the option key spelling — it must be exactly `schema`.","Verify the schema variable is actually defined/awaited before construction (e.g. an async schema loader returning undefined).","Add an early existence check on your schema config before instantiating the processor."],"exampleFix":"// before\nnew StructuredOutputProcessor({ model });\n// after\nimport { z } from 'zod';\nnew StructuredOutputProcessor({ model, schema: z.object({ answer: z.string() }) });","handlingStrategy":"validation","validationCode":"if (!schema) throw new TypeError('StructuredOutputProcessor: schema is required');\nconst processor = new StructuredOutputProcessor({ schema, model });","typeGuard":"function hasSchema<T>(o: StructuredOutputOptions<T>): o is StructuredOutputOptions<T> & { schema: NonNullable<StructuredOutputOptions<T>['schema']> } {\n  return Boolean(o.schema);\n}","tryCatchPattern":"import { MastraError } from '@mastra/core';\ntry {\n  processor = new StructuredOutputProcessor(opts);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'STRUCTURED_OUTPUT_PROCESSOR_SCHEMA_REQUIRED') {\n    console.error('schema missing in structured output config');\n  }\n  throw e;\n}","preventionTips":["Type the options with a non-optional schema so TypeScript rejects missing schemas at compile time.","Co-locate the schema definition with processor construction to avoid undefined references.","Test processor construction in CI with your actual schema registry."],"tags":["configuration","schema","structured-output","constructor"],"backgroundTag":"missing-required-option","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}