mastra-ai/mastra · error · MastraError

STRUCTURED_OUTPUT_PROCESSOR_MODEL_REQUIRED

STRUCTURED_OUTPUT_PROCESSOR_MODEL_REQUIRED

Error message

StructuredOutputProcessor requires a model to be provided either in options or as fallback

What it means

StructuredOutputProcessor delegates the actual generation to a language model. It can take the model from `options.model`; if none is supplied (and no fallback is available), it has nothing to run, so the constructor throws a MastraError with id STRUCTURED_OUTPUT_PROCESSOR_MODEL_REQUIRED (domain AGENT, category USER).

Source

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

  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;
    this.errorStrategy = options.errorStrategy ?? 'strict';
    this.fallbackValue = options.fallbackValue;
    this.jsonPromptInjection = options.jsonPromptInjection;
    this.providerOptions = options.providerOptions;
    this.logger = options.logger;
    this.structuringInstructions = options.instructions || this.generateInstructions();
    // Create internal structuring agent as fallback (used when no explicit agent is set)
    this.structuringAgent = new Agent({

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a model instance or model string: `new StructuredOutputProcessor({ schema, model: 'openai/gpt-4o' })`.
2. If constructing per-request, confirm the model factory actually returns a model (check API key/env vars).
3. Attach the processor to an Agent configured with a model so the fallback path applies.
4. Validate the model value is non-undefined before constructing the processor.

Example fix

// before
new StructuredOutputProcessor({ schema: MySchema });
// after
new StructuredOutputProcessor({ schema: MySchema, model: 'openai/gpt-4o' });

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

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

try {
  processor = new StructuredOutputProcessor(opts);
} catch (e) {
  if (e instanceof MastraError && e.id === 'STRUCTURED_OUTPUT_PROCESSOR_MODEL_REQUIRED') {
    processor = new StructuredOutputProcessor({ ...opts, model: DEFAULT_MODEL });
  } else throw e;
}

When it happens

Trigger: `new StructuredOutputProcessor({ schema })` with no `model` key, or `model: undefined` — e.g. a model created conditionally, an invalid provider string that resolves to undefined, or forgetting to pass the model when the processor is not attached to an agent that would supply a fallback.

Common situations: Refactoring to share one model instance across processors and dropping the reference, model factory returning undefined on missing API key, examples that rely on agent-level fallback models while using the processor standalone.

Related errors

• STRUCTURED_OUTPUT_PROCESSOR_SCHEMA_REQUIRED
• SystemPromptScrubber requires a model for detection
• 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

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