mastra-ai/mastra · error · Error

Unsupported model version: ${(model as any).specificationVer

Error message

Unsupported model version: ${(model as any).specificationVersion}. Model must implement doStream.${hint}

What it means

The durable LLM execution step checks isSupportedLanguageModel(model) before streaming. If the check fails, it throws reporting the object's specificationVersion and requires the model to implement doStream. When the object is the `__metadataOnly` stub (error 1073), the message appends a hint that the model could not be resolved from the run registry or Mastra instance.

Source

Thrown at packages/core/src/agent/durable/workflows/steps/llm-execution.ts:336

      for (let modelIndex = 0; modelIndex < modelList.length; modelIndex++) {
        const modelEntry = modelList[modelIndex]!;
        const maxRetries = modelEntry.maxRetries || 0;

        for (let attempt = 0; attempt <= maxRetries; attempt++) {
          try {
            // Resolve the model - for single model case (no modelList), use resolved model
            // For model list case, try registry first (works with mock models), then config resolution (for Inngest)
            const model = !hasModelList
              ? resolvedModel
              : (resolvedModelList?.find(m => m.id === modelEntry.id)?.model ??
                (await resolveModelFromListEntry(modelEntry, mastra as Mastra)));

            // Check if model is supported
            if (!isSupportedLanguageModel(model)) {
              const hint = (model as any).__metadataOnly
                ? ' The model could not be resolved from the run registry or Mastra instance.'
                : '';
              throw new Error(
                `Unsupported model version: ${(model as any).specificationVersion}. Model must implement doStream.${hint}`,
              );
            }

            // 5. Prepare tools - cast through unknown as CoreTool and ToolSet are structurally compatible at runtime
            let currentModel = model;
            let currentTools = tools as unknown as ToolSet;
            let currentToolChoice = execOptions.toolChoice as ToolChoice<ToolSet> | undefined;
            let currentActiveTools = execOptions.activeTools;
            let currentModelSettings: Record<string, unknown> = { ...(execOptions.modelSettings ?? {}) };
            let currentProviderOptions: SharedProviderOptions | undefined = mergeProviderOptions(
              execOptions.providerOptions,
              modelEntry.config.providerOptions,
            ) as SharedProviderOptions | undefined;

            // 6. Rebuild MODEL_GENERATION span from passed data
            // For durable execution, ONE model_generation span is created BEFORE the workflow starts
            // and passed through each iteration. This ensures all steps are children of the same span.

View on GitHub (pinned to 75dd419e61)

Solutions

If the hint mentions the run registry, fix model resolution first (pass mastra / re-register the model — see error 1073).
Use a LanguageModelV2-compatible model that implements doStream.
Upgrade custom model wrappers to the current specificationVersion.
Verify you're not importing a stale v4 model factory in the durable path.

Example fix

// before
import { openai } from '@ai-sdk/openai'; // v4 factory producing non-doStream model
const agent = new Agent({ model: openai('gpt-4o') });
// after
import { createOpenAI } from '@ai-sdk/openai'; // current major aligned with core
const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const agent = new Agent({ model: openai('gpt-4o') });

Defensive patterns

Strategy: type-guard

Validate before calling

if (!isSupportedLanguageModel(model)) {
  throw new Error('Configured model does not implement doStream (LanguageModelV2 required)');
}

Type guard

function isStreamableModel(m: unknown): m is MastraLanguageModel {
  return (
    !!m && typeof m === 'object' &&
    (m as any).specificationVersion === 'v2' &&
    typeof (m as any).doStream === 'function'
  );
}

Try / catch

try {
  await durableAgent.generate({ messages });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unsupported model version')) {
    logger.error('Replace model with a doStream-compatible (LanguageModelV2) instance');
  }
  throw e;
}

Prevention

Pin AI SDK provider packages to majors compatible with @mastra/core's doStream contract
Add a boot-time isSupportedLanguageModel check for every agent model
For custom models, implement doStream and set specificationVersion correctly
Never reuse v4-era model factories in durable execution paths

When it happens

Trigger: Passing a v1-style/legacy model object (no doStream/specificationVersion mismatch) into a durable agent run, or the resolveModel fallback stub being used because the real model wasn't found.

Common situations: Mixing AI SDK v4 models with a v5/doStream-based core, custom model wrappers missing specificationVersion, or resuming runs whose models can't be re-hydrated after a deploy.

Related errors

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