mastra-ai/mastra · error · Error

Sub-agent ${agent.id} returned a v1 model but does not imple

Error message

Sub-agent ${agent.id} returned a v1 model but does not implement generateLegacy

What it means

Thrown when a sub-agent, invoked from a parent agent's tool/delegation path, resolves to a 'v1' model version (legacy AI SDK v1 model surface) but the sub-agent instance does not expose a `generateLegacy` method. The parent cannot drive a v1 model through the modern generate path, so it fails explicitly instead of erroring opaquely later.

Source

Thrown at packages/core/src/agent/agent.ts:5456

                    runId: generateResult.runId,
                    isAgentSuspend: true,
                  });
                }

                result = {
                  text: generateResult.text,
                  finishReason: generateResult.finishReason,
                  subAgentThreadId: effectiveGenerateThreadId,
                  subAgentResourceId: effectiveGenerateResourceId,
                  subAgentToolResults,
                  usage: generateResult.usage,
                };
              } else if (
                (methodType === 'generate' || methodType === 'generateLegacy') &&
                resolvedModelVersion === 'v1'
              ) {
                if (typeof resolvedAgent.generateLegacy !== 'function') {
                  throw new Error(`Sub-agent ${agent.id} returned a v1 model but does not implement generateLegacy`);
                }
                const generateResult = await resolvedAgent.generateLegacy(messagesForSubAgent, {
                  requestContext: subAgentRequestContext,
                  actor: invocationActor,
                  ...resolveObservabilityContext(context ?? {}),
                  context: filteredContextMessages as unknown as CoreMessage[],
                  ...subAgentAbortOptions,
                });
                result = {
                  text: generateResult.text,
                  ...(generateResult.usage ? { usage: generateResult.usage } : {}),
                };
              } else if (
                (methodType === 'stream' || methodType === 'streamLegacy') &&
                supportedLanguageModelSpecifications.includes(resolvedModelVersion)
              ) {
                const streamResult = shouldResumeSubAgent
                  ? await resolvedAgent.resumeStream(resumeData, {

View on GitHub (pinned to 75dd419e61)

Solutions

Upgrade the sub-agent's model to the current (v2) model version so the legacy path is not needed
Ensure all agents come from the same @mastra/core version so generateLegacy is present
If you must keep the v1 model, use a core version whose Agent implements generateLegacy
Check for a custom Agent subclass that overrides/omits generateLegacy and restore it

Example fix

// before
subAgent = new Agent({ name: 'child', model: legacyV1Model });
// after
subAgent = new Agent({ name: 'child', model: currentV2Model });

Defensive patterns

Strategy: validation

Validate before calling

function subAgentSupportsGenerate(agent) {
  return typeof agent.generate === 'function' &&
    (agent.generateLegacy !== undefined || agent.__modelVersion !== 'v1');
}

Type guard

function canGenerateLegacy(agent) {
  return typeof (agent as { generateLegacy?: unknown })?.generateLegacy === 'function';
}

Try / catch

try {
  return await parentAgent.generate(prompt, { agents: [subAgent] });
} catch (e) {
  if (typeof e?.message === 'string' && e.message.includes('does not implement generateLegacy')) {
    throw new Error(`Sub-agent ${subAgentName} needs a v2 model or an upgraded core version`);
  }
  throw e;
}

Prevention

Keep all agents on the same @mastra/core version in a network
Migrate all models off v1/legacy adapters before mixing agents
Add a startup check that each sub-agent exposes the needed generate/stream methods
Pin model provider packages consistently across services

When it happens

Trigger: Parent agent delegation/tool call with `methodType === 'generate' || 'generateLegacy'`, the sub-agent resolves `resolvedModelVersion === 'v1'`, and `typeof resolvedAgent.generateLegacy !== 'function'` — typically a mixed-version setup where agents were constructed by different @mastra/core or model-provider versions.

Common situations: Gradual migration from legacy to v2 models where some agents still hold v1 model instances; mixing agents from different mastra packages in one network; a custom Agent subclass overriding generate and dropping the legacy shim.

Related errors

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