mastra-ai/mastra · error · MastraError

AGENT_GENERATE_V2_MODEL_NOT_SUPPORTED

AGENT_GENERATE_V2_MODEL_NOT_SUPPORTED

Error message

Models with specificationVersion "${specVersion}" are not supported for generateLegacy(). Please use generate() instead.

What it means

generateLegacy() only supports v1 language models. If the agent's model (or the model resolved at runtime) has a specificationVersion of "v2" (the AI SDK v5 model spec), the legacy path rejects it and throws AGENT_GENERATE_V2_MODEL_NOT_SUPPORTED, directing you to the modern generate() API.

Source

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

      ...generateOptions,
      experimental_generateMessageId:
        defaultGenerateOptionsLegacy.experimental_generateMessageId ||
        this.capabilities.mastra?.generateId?.bind(this.capabilities.mastra),
    };

    const { llm, before, after } = await this.prepareLLMOptions(messages, mergedGenerateOptions as any, 'generate');

    if (llm.getModel().specificationVersion !== 'v1') {
      const specVersion = llm.getModel().specificationVersion;
      this.capabilities.logger.error(
        `Models with specificationVersion "${specVersion}" are not supported for generateLegacy. Please use generate() instead.`,
        {
          modelId: llm.getModel().modelId,
          specificationVersion: specVersion,
        },
      );

      throw new MastraError({
        id: 'AGENT_GENERATE_V2_MODEL_NOT_SUPPORTED',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        details: {
          modelId: llm.getModel().modelId,
          specificationVersion: specVersion,
        },
        text: `Models with specificationVersion "${specVersion}" are not supported for generateLegacy(). Please use generate() instead.`,
      });
    }

    const llmToUse = llm as MastraLLMV1;
    const beforeResult = await before();
    const { messageList, requestContext: contextWithMemory } = beforeResult;
    const traceId = beforeResult.agentSpan?.externalTraceId;
    const spanId = beforeResult.agentSpan?.id;

    // Check for tripwire and return early if triggered

View on GitHub (pinned to 75dd419e61)

Solutions

1. Replace generateLegacy() calls with agent.generate(), which supports v2 models.
2. If legacy behavior is required, configure the agent with a v1-spec model (specificationVersion "v1").
3. Audit remaining generateLegacy/streamLegacy call sites during migration and update them all at once.

Example fix

// before
const res = await agent.generateLegacy(messages); // agent uses a v2-spec model
// after
const res = await agent.generate(messages);

function assertV1ModelForLegacy(model: { specificationVersion?: string }) {
  if (model.specificationVersion !== 'v1') {
    throw new Error(`generateLegacy() requires a v1-spec model; got "${model.specificationVersion}" — use agent.generate()`);
  }
}

function isV1SpecModel(m: unknown): m is { specificationVersion: 'v1' } {
  return !!m && typeof m === 'object' && (m as any).specificationVersion === 'v1';
}

try {
  return await agent.generateLegacy(msgs, opts);
} catch (err) {
  if ((err as any).id === 'AGENT_GENERATE_V2_MODEL_NOT_SUPPORTED') {
    return agent.generate(msgs, opts);
  }
  throw err;
}

When it happens

Trigger: Calling agent.generateLegacy() on an Agent configured with a v2-spec model (e.g. models created via the current model router / AI SDK v5 adapters), including models swapped dynamically via doGenerate/model resolution.

Common situations: Upgraded a project to v2 models but kept legacy generateLegacy() calls; shared model factory returns v2 models while older code paths still use the legacy API.

Related errors

• AGENT_STREAM_V2_MODEL_NOT_SUPPORTED
• AGENT_GENERATE_LEGACY_STRUCTURED_OUTPUT_NOT_SUPPORTED
• toAISdkFormat() has been deprecated. Please use toAISdkStrea
• MastraFactory: 'sandbox' is now a callback, not an options o
• Repository ${id} not found in organization ${orgId}

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