mastra-ai/mastra · error · MastraError

STRUCTURED_OUTPUT_PROCESSOR_SCHEMA_REQUIRED

STRUCTURED_OUTPUT_PROCESSOR_SCHEMA_REQUIRED

Error message

StructuredOutputProcessor requires a schema to be provided

What it means

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.

Source

Thrown at packages/core/src/processors/processors/structured-output.ts:54

  readonly id = STRUCTURED_OUTPUT_PROCESSOR_NAME;
  readonly name = 'Structured Output';

  public schema: StandardSchemaWithJSON<OUTPUT>;
  private structuringAgent: Agent<any, any, undefined>;
  private structuringModel: MastraModelConfig;
  private structuringInstructions: string;
  private agent?: Agent<any, any, any>;
  private useAgent = false;
  private errorStrategy: 'strict' | 'warn' | 'fallback';
  private fallbackValue?: OUTPUT;
  private isStructuringAgentStreamStarted = false;
  private jsonPromptInjection?: boolean | 'system' | 'inline' | 'auto';
  private providerOptions?: ProviderOptions;
  private logger?: IMastraLogger;

  constructor(options: StructuredOutputOptions<OUTPUT>) {
    if (!options.schema) {
      throw new MastraError({
        id: 'STRUCTURED_OUTPUT_PROCESSOR_SCHEMA_REQUIRED',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text: 'StructuredOutputProcessor requires a schema to be provided',
      });
    }
    if (!options.model) {
      throw new MastraError({
        id: 'STRUCTURED_OUTPUT_PROCESSOR_MODEL_REQUIRED',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text: 'StructuredOutputProcessor requires a model to be provided either in options or as fallback',
      });
    }

    this.schema = options.schema;
    this.structuringModel = options.model;
    this.useAgent = options.useAgent ?? false;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a schema: `new StructuredOutputProcessor({ schema: z.object({ ... }) })`.
2. Check the option key spelling — it must be exactly `schema`.
3. Verify the schema variable is actually defined/awaited before construction (e.g. an async schema loader returning undefined).
4. Add an early existence check on your schema config before instantiating the processor.

Example fix

// before
new StructuredOutputProcessor({ model });
// after
import { z } from 'zod';
new StructuredOutputProcessor({ model, schema: z.object({ answer: z.string() }) });

if (!schema) throw new TypeError('StructuredOutputProcessor: schema is required');
const processor = new StructuredOutputProcessor({ schema, model });

function hasSchema<T>(o: StructuredOutputOptions<T>): o is StructuredOutputOptions<T> & { schema: NonNullable<StructuredOutputOptions<T>['schema']> } {
  return Boolean(o.schema);
}

import { MastraError } from '@mastra/core';
try {
  processor = new StructuredOutputProcessor(opts);
} catch (e) {
  if (e instanceof MastraError && e.id === 'STRUCTURED_OUTPUT_PROCESSOR_SCHEMA_REQUIRED') {
    console.error('schema missing in structured output config');
  }
  throw e;
}

When it happens

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

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

Related errors

• STRUCTURED_OUTPUT_PROCESSOR_MODEL_REQUIRED
• Better Auth instance is required. Please provide the auth op
• Okta domain is required. Provide it in the options or set OK
• Okta client ID is required. Provide it in the options or set
• MastraFactory: 'storage' is required. Pass a FactoryStorage

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