mastra-ai/mastra · error · MastraError

PROCESSOR_RETURNED_UNSUPPORTED_MODEL

PROCESSOR_RETURNED_UNSUPPORTED_MODEL

Error message

Processor ${processor.id} returned an unsupported model version ${resolvedModel.specificationVersion} in step ${stepNumber}. Only ${supportedLanguageModelSpecifications.join(', ')} models are supported in processInputStep.

What it means

Thrown when a processor's `processInputStep` returns a result with a `model` that resolves to a LanguageModel whose `specificationVersion` is not in the supported set (e.g. not LanguageModelV2/V3). The runner validates the resolved model per input step so the LLM call won't fail downstream with an incompatible model interface.

Source

Thrown at packages/core/src/processors/runner.ts:2613

          domain: 'AGENT',
          id: 'PROCESSOR_RETURNED_EXTERNAL_MESSAGE_LIST',
          text: `Processor ${processor.id} returned a MessageList instance other than the one that was passed in as an argument. New external message list instances are not supported. Use the messageList argument instead.`,
        });
      }
      if (result.messages && result.messageList) {
        throw new MastraError({
          category: 'USER',
          domain: 'AGENT',
          id: 'PROCESSOR_RETURNED_MESSAGES_AND_MESSAGE_LIST',
          text: `Processor ${processor.id} returned both messages and messageList. Only one of these is allowed.`,
        });
      }
      const { model: _model, ...rest } = result;
      if (result.model) {
        const resolvedModel = await resolveModelConfig(result.model);
        const isSupported = isSupportedLanguageModel(resolvedModel);
        if (!isSupported) {
          throw new MastraError({
            category: 'USER',
            domain: 'AGENT',
            id: 'PROCESSOR_RETURNED_UNSUPPORTED_MODEL',
            text: `Processor ${processor.id} returned an unsupported model version ${resolvedModel.specificationVersion} in step ${stepNumber}. Only ${supportedLanguageModelSpecifications.join(', ')} models are supported in processInputStep.`,
          });
        }

        return {
          model: resolvedModel,
          ...rest,
        };
      }

      return rest;
    }

    return {};
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade/downgrade the model package so the model's specificationVersion matches the supported versions listed in the error.
2. Construct the model with the AI SDK's provider factory (e.g. `openai('gpt-4o')`) rather than a raw SDK client.
3. Use the same model config shape the agent itself accepts (resolveModelConfig-compatible), and verify `resolveModelConfig(result.model).specificationVersion` before returning it.

Example fix

// before: raw SDK client returned from processor
return { model: new OpenAIClient().chat, messages };

// after: AI SDK model with supported specificationVersion
import { openai } from '@ai-sdk/openai';
return { model: openai('gpt-4o'), messages };

const resolved = await resolveModelConfig(result.model);
if (!isSupportedLanguageModel(resolved)) {
  throw new Error(
    `Model specificationVersion ${resolved.specificationVersion} is unsupported; use one of: ${supportedLanguageModelSpecifications.join(', ')}`,
  );
}

function isSupportedLanguageModel(
  m: unknown,
): m is { specificationVersion: 'v2' | 'v3' } {
  return !!m && typeof m === 'object' &&
    (m as any).specificationVersion !== undefined &&
    supportedLanguageModelSpecifications.includes((m as any).specificationVersion);
}

try {
  const res = await agent.generate(input);
} catch (e) {
  if (e instanceof MastraError && e.id === 'PROCESSOR_RETURNED_UNSUPPORTED_MODEL') {
    console.error(`Processor model unsupported: ${e.message}`);
    return runWithDefaultModel(input);
  }
  throw e;
}

When it happens

Trigger: A processor overrides the step model via `result.model` with: a raw provider SDK client (not an AI SDK model); a model specificationVersion outside `supportedLanguageModelSpecifications` (e.g. V1 from an old @ai-sdk version); an object that resolves to an unsupported shape.

Common situations: Mixing @ai-sdk v1 and v2 packages in one app so the wrong specificationVersion is produced; passing a provider's native client instead of `provider(modelId)`; hardcoding a model router result that predates the supported spec.

Related errors

• AGENT_GENERATE_V1_MODEL_NOT_SUPPORTED
• AGENT_STREAM_V1_MODEL_NOT_SUPPORTED
• Observational Memory processor not available
• runId is required when resumeData is provided
• Agent ${agentId} not found

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