{"record":{"id":"762b8bd43e439427","repo":"mastra-ai/mastra","slug":"agent-generate-v2-model-not-supported","errorCode":"AGENT_GENERATE_V2_MODEL_NOT_SUPPORTED","errorMessage":"Models with specificationVersion \"${specVersion}\" are not supported for generateLegacy(). Please use generate() instead.","messagePattern":"Models with specificationVersion \"(.+?)\" are not supported for generateLegacy\\(\\)\\. Please use generate\\(\\) instead\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/agent-legacy.ts","lineNumber":997,"sourceCode":"      ...generateOptions,\n      experimental_generateMessageId:\n        defaultGenerateOptionsLegacy.experimental_generateMessageId ||\n        this.capabilities.mastra?.generateId?.bind(this.capabilities.mastra),\n    };\n\n    const { llm, before, after } = await this.prepareLLMOptions(messages, mergedGenerateOptions as any, 'generate');\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 generateLegacy. Please use generate() instead.`,\n        {\n          modelId: llm.getModel().modelId,\n          specificationVersion: specVersion,\n        },\n      );\n\n      throw new MastraError({\n        id: 'AGENT_GENERATE_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 generateLegacy(). Please use generate() instead.`,\n      });\n    }\n\n    const llmToUse = llm as MastraLLMV1;\n    const beforeResult = await before();\n    const { messageList, requestContext: contextWithMemory } = beforeResult;\n    const traceId = beforeResult.agentSpan?.externalTraceId;\n    const spanId = beforeResult.agentSpan?.id;\n\n    // Check for tripwire and return early if triggered","sourceCodeStart":979,"sourceCodeEnd":1015,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/agent-legacy.ts#L979-L1015","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Replace generateLegacy() calls with agent.generate(), which supports v2 models.","If legacy behavior is required, configure the agent with a v1-spec model (specificationVersion \"v1\").","Audit remaining generateLegacy/streamLegacy call sites during migration and update them all at once."],"exampleFix":"// before\nconst res = await agent.generateLegacy(messages); // agent uses a v2-spec model\n// after\nconst res = await agent.generate(messages);","handlingStrategy":"validation","validationCode":"function assertV1ModelForLegacy(model: { specificationVersion?: string }) {\n  if (model.specificationVersion !== 'v1') {\n    throw new Error(`generateLegacy() requires a v1-spec model; got \"${model.specificationVersion}\" — use agent.generate()`);\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.generateLegacy(msgs, opts);\n} catch (err) {\n  if ((err as any).id === 'AGENT_GENERATE_V2_MODEL_NOT_SUPPORTED') {\n    return agent.generate(msgs, opts);\n  }\n  throw err;\n}","preventionTips":["Once on v2-spec models, remove all generateLegacy/generate calls through the legacy path.","Centralize model creation so spec version is known and asserted in one place.","Search code for 'Legacy(' during upgrades and migrate them together."],"tags":["agent","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"}