mastra-ai/mastra · error · MastraError

AGENT_GENERATE_LEGACY_STRUCTURED_OUTPUT_NOT_SUPPORTED

AGENT_GENERATE_LEGACY_STRUCTURED_OUTPUT_NOT_SUPPORTED

Error message

This method does not support structured output. Please use generate() instead.

What it means

generateLegacy() is the deprecated v1 generate path. It does not support structured output, so passing a `structuredOutput` option (or OUTPUT schema) throws immediately with this MastraError. Use the modern generate() API which supports structured output natively.

Source

Thrown at packages/core/src/agent/agent-legacy.ts:963

        });
        return afterResult;
      },
    };
  }

  /**
   * Legacy implementation of generate method using AI SDK v4 models.
   * Use this method if you need to continue using AI SDK v4 models.
   */
  async generateLegacy<
    OUTPUT extends ZodSchema | JSONSchema7 | undefined = undefined,
    EXPERIMENTAL_OUTPUT extends ZodSchema | JSONSchema7 | undefined = undefined,
  >(
    messages: MessageListInput,
    generateOptions: AgentGenerateOptions<OUTPUT, EXPERIMENTAL_OUTPUT> = {},
  ): Promise<OUTPUT extends undefined ? GenerateTextResult<any, EXPERIMENTAL_OUTPUT> : GenerateObjectResult<OUTPUT>> {
    if ('structuredOutput' in generateOptions && generateOptions.structuredOutput) {
      throw new MastraError({
        id: 'AGENT_GENERATE_LEGACY_STRUCTURED_OUTPUT_NOT_SUPPORTED',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text: 'This method does not support structured output. Please use generate() instead.',
      });
    }

    const defaultGenerateOptionsLegacy = await Promise.resolve(
      this.capabilities.getDefaultGenerateOptionsLegacy({
        requestContext: generateOptions.requestContext,
      }),
    );

    const mergedGenerateOptions: AgentGenerateOptions<OUTPUT, EXPERIMENTAL_OUTPUT> = {
      ...defaultGenerateOptionsLegacy,
      ...generateOptions,
      experimental_generateMessageId:
        defaultGenerateOptionsLegacy.experimental_generateMessageId ||

View on GitHub (pinned to 75dd419e61)

Solutions

1. Switch to agent.generate() with the structuredOutput option (or use generate() with a Zod schema) — the modern API supports structured output.
2. If you must stay on generateLegacy() temporarily, remove the structuredOutput option and parse the text output manually.

Example fix

// before
const result = await agent.generateLegacy(prompt, { structuredOutput: schema });
// after
const result = await agent.generate(prompt, { structuredOutput: schema });

function assertLegacySafe(opts: { structuredOutput?: unknown }) {
  if ('structuredOutput' in opts && opts.structuredOutput) {
    throw new Error('structuredOutput requires agent.generate(), not generateLegacy()');
  }
}

try {
  return await agent.generateLegacy(msgs, opts);
} catch (err) {
  if ((err as any).id === 'AGENT_GENERATE_LEGACY_STRUCTURED_OUTPUT_NOT_SUPPORTED') {
    return agent.generate(msgs, opts); // automatic fallback to modern API
  }
  throw err;
}

When it happens

Trigger: Calling the deprecated agent.generateLegacy() with `{ structuredOutput: z.object(...) }` (or a JSON schema) in AgentGenerateOptions.

Common situations: Migrating old code that used generate() with a schema after upgrading, or code generators/examples pinned to the legacy API attempting to add structured output.

Related errors

• AGENT_GENERATE_V2_MODEL_NOT_SUPPORTED
• AGENT_STREAM_V2_MODEL_NOT_SUPPORTED
• No result received from agent execution on iteration ${itera
• STRUCTURED_OUTPUT_OPTIONS_REQUIRED
• CursorSDKAgent does not support structuredOutput because the

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