mastra-ai/mastra · error · MastraError

AGENT_STREAM_V2_MODEL_NOT_SUPPORTED

AGENT_STREAM_V2_MODEL_NOT_SUPPORTED

Error message

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

What it means

The streaming counterpart of AGENT_GENERATE_V2_MODEL_NOT_SUPPORTED: streamLegacy() only works with v1-spec models, and throws this error when the agent's model has specificationVersion "v2". Use the modern stream() API instead.

Source

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

      ...streamOptions,
      experimental_generateMessageId:
        defaultStreamOptionsLegacy.experimental_generateMessageId ||
        this.capabilities.mastra?.generateId?.bind(this.capabilities.mastra),
    };

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

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

      throw new MastraError({
        id: 'AGENT_STREAM_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 streamLegacy(). Please use stream() instead.`,
      });
    }

    const beforeResult = await before();
    const traceId = beforeResult.agentSpan?.externalTraceId;
    const spanId = beforeResult.agentSpan?.id;

    // Check for tripwire and return early if triggered
    if (beforeResult.tripwire) {
      // End agent span with tripwire information

View on GitHub (pinned to 75dd419e61)

Solutions

1. Replace streamLegacy() with agent.stream(), which supports v2 models.
2. Alternatively pin the agent to a v1-spec model if the legacy streaming path is temporarily required.
3. Grep the codebase for streamLegacy/generateLegacy and migrate all call sites together.

Example fix

// before
const stream = await agent.streamLegacy(prompt); // v2-spec model
// after
const stream = await agent.stream(prompt);

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

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

try {
  return await agent.streamLegacy(prompt, opts);
} catch (err) {
  if ((err as any).id === 'AGENT_STREAM_V2_MODEL_NOT_SUPPORTED') {
    return agent.stream(prompt, opts);
  }
  throw err;
}

When it happens

Trigger: Calling agent.streamLegacy() on an Agent whose model is a v2-spec model (AI SDK v5 / current model router), including dynamically resolved models.

Common situations: Projects migrated to v2 models but still streaming via the legacy path; old streaming examples kept after a model upgrade.

Related errors

• AGENT_GENERATE_V2_MODEL_NOT_SUPPORTED
• AGENT_GENERATE_LEGACY_STRUCTURED_OUTPUT_NOT_SUPPORTED
• No result received from agent execution on iteration ${itera
• No result received from agent execution
• Sub-agent ${agent.id} returned a v1 model but does not imple

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