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 streamLegacy

What it means

Streaming counterpart to the generateLegacy error: when a sub-agent resolves to a 'v1' model version but its instance lacks a `streamLegacy` function, the parent's streaming delegation path throws instead of attempting to call an undefined method.

Source

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

                  });
                }

                // Use streamResult.text (a delayed promise) which resolves to the
                // output-processor-modified text, rather than the raw accumulated text-deltas.
                const processedText = await streamResult.text;
                const subAgentFinishReason = await streamResult.finishReason;
                const subAgentUsage = await streamResult.usage;
                result = {
                  text: processedText,
                  finishReason: subAgentFinishReason,
                  subAgentThreadId: effectiveStreamThreadId,
                  subAgentResourceId: effectiveStreamResourceId,
                  subAgentToolResults,
                  usage: subAgentUsage,
                };
              } else {
                if (typeof resolvedAgent.streamLegacy !== 'function') {
                  throw new Error(`Sub-agent ${agent.id} returned a v1 model but does not implement streamLegacy`);
                }
                const streamResult = await resolvedAgent.streamLegacy(effectivePrompt, {
                  requestContext: subAgentRequestContext,
                  actor: invocationActor,
                  ...resolveObservabilityContext(context ?? {}),
                  ...subAgentAbortOptions,
                });

                let fullText = '';
                for await (const chunk of streamResult.fullStream) {
                  if (context?.writer) {
                    // Data chunks from writer.custom() should bubble up directly without wrapping
                    if (chunk.type.startsWith('data-')) {
                      // Write data chunks directly to original stream to bubble up
                      await context.writer.custom(chunk as any);
                    } else {
                      await context.writer.write(chunk);
                    }

View on GitHub (pinned to 75dd419e61)

Solutions

Upgrade the sub-agent's model to the current version so streaming uses the modern path
Align @mastra/core versions across all agents in the network
If keeping a v1 model, use a core version where Agent provides streamLegacy
Inspect custom Agent subclasses for a missing streamLegacy implementation

Example fix

// before
model: openai('gpt-4o') /* legacy v1 adapter */
// after
model: currentProviderAdapter('gpt-4o') /* v2 */

Defensive patterns

Strategy: validation

Validate before calling

function subAgentSupportsStream(agent) {
  return typeof agent.stream === 'function' &&
    (agent.streamLegacy !== undefined || agent.__modelVersion !== 'v1');
}

Type guard

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

Try / catch

try {
  return await parentAgent.stream(prompt, { agents: [subAgent] });
} catch (e) {
  if (typeof e?.message === 'string' && e.message.includes('does not implement streamLegacy')) {
    logger.error('sub-agent model is v1 without streamLegacy; upgrade model or core');
    return errorStream('sub-agent-incompatible');
  }
  throw e;
}

Prevention

Upgrade legacy v1 model adapters to current provider adapters
Run a smoke stream against every sub-agent in CI
Avoid custom Agent subclasses that drop streamLegacy while keeping v1 models
Align model-provider and core package versions in lockfile

When it happens

Trigger: Parent agent delegation/streaming call where `resolvedModelVersion === 'v1'` and `typeof resolvedAgent.streamLegacy !== 'function'`; typically caused by mixed @mastra/core/model-provider versions across parent and sub-agents.

Common situations: Same mixed-version migration scenarios as the generate variant, surfaced via `stream()`/loop streaming calls; custom Agent implementations that implement modern stream but not streamLegacy while still holding a v1 model.

Related errors

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