{"record":{"id":"de345c950ef3ce25","repo":"mastra-ai/mastra","slug":"agent-stream-v2-model-not-supported","errorCode":"AGENT_STREAM_V2_MODEL_NOT_SUPPORTED","errorMessage":"Models with specificationVersion \"${specVersion}\" are not supported for streamLegacy(). Please use stream() instead.","messagePattern":"Models with specificationVersion \"(.+?)\" are not supported for streamLegacy\\(\\)\\. Please use stream\\(\\) instead\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/agent-legacy.ts","lineNumber":1338,"sourceCode":"      ...streamOptions,\n      experimental_generateMessageId:\n        defaultStreamOptionsLegacy.experimental_generateMessageId ||\n        this.capabilities.mastra?.generateId?.bind(this.capabilities.mastra),\n    };\n\n    const { llm, before, after } = await this.prepareLLMOptions(messages, mergedStreamOptions as any, 'stream');\n\n    if (llm.getModel().specificationVersion !== 'v1') {\n      const specVersion = llm.getModel().specificationVersion;\n      this.capabilities.logger.error(\n        `Models with specificationVersion \"${specVersion}\" are not supported for streamLegacy. Please use stream() instead.`,\n        {\n          modelId: llm.getModel().modelId,\n          specificationVersion: specVersion,\n        },\n      );\n\n      throw new MastraError({\n        id: 'AGENT_STREAM_V2_MODEL_NOT_SUPPORTED',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        details: {\n          modelId: llm.getModel().modelId,\n          specificationVersion: specVersion,\n        },\n        text: `Models with specificationVersion \"${specVersion}\" are not supported for streamLegacy(). Please use stream() instead.`,\n      });\n    }\n\n    const beforeResult = await before();\n    const traceId = beforeResult.agentSpan?.externalTraceId;\n    const spanId = beforeResult.agentSpan?.id;\n\n    // Check for tripwire and return early if triggered\n    if (beforeResult.tripwire) {\n      // End agent span with tripwire information","sourceCodeStart":1320,"sourceCodeEnd":1356,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/agent-legacy.ts#L1320-L1356","documentation":"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.","triggerScenarios":"Calling agent.streamLegacy() on an Agent whose model is a v2-spec model (AI SDK v5 / current model router), including dynamically resolved models.","commonSituations":"Projects migrated to v2 models but still streaming via the legacy path; old streaming examples kept after a model upgrade.","solutions":["Replace streamLegacy() with agent.stream(), which supports v2 models.","Alternatively pin the agent to a v1-spec model if the legacy streaming path is temporarily required.","Grep the codebase for streamLegacy/generateLegacy and migrate all call sites together."],"exampleFix":"// before\nconst stream = await agent.streamLegacy(prompt); // v2-spec model\n// after\nconst stream = await agent.stream(prompt);","handlingStrategy":"validation","validationCode":"function assertV1ModelForLegacyStream(model: { specificationVersion?: string }) {\n  if (model.specificationVersion !== 'v1') {\n    throw new Error(`streamLegacy() requires a v1-spec model; got \"${model.specificationVersion}\" — use agent.stream()`);\n  }\n}","typeGuard":"function isV1SpecModel(m: unknown): m is { specificationVersion: 'v1' } {\n  return !!m && typeof m === 'object' && (m as any).specificationVersion === 'v1';\n}","tryCatchPattern":"try {\n  return await agent.streamLegacy(prompt, opts);\n} catch (err) {\n  if ((err as any).id === 'AGENT_STREAM_V2_MODEL_NOT_SUPPORTED') {\n    return agent.stream(prompt, opts);\n  }\n  throw err;\n}","preventionTips":["Replace streamLegacy with agent.stream() wherever v2 models are in use.","Combine generate/stream migrations in one change to avoid mixed legacy/modern paths.","Add unit coverage asserting agents built by your model factory work with the modern stream API."],"tags":["agent","streaming","model-spec","deprecated-api","migration"],"backgroundTag":"unsupported-model-specification","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}