mastra-ai/mastra · error

Invalid model provided. Model must be a MastraLanguageModel

Error message

Invalid model provided. Model must be a MastraLanguageModel instance (e.g., openai("gpt-4"), anthropic("claude-3-5-sonnet"), etc.)

What it means

When resolving the model for an agent-builder request, if a model is present in the request context but fails isValidMastraLanguageModel, this error is thrown: 'Invalid model provided. Model must be a MastraLanguageModel instance...'. It guards against strings, plain objects, or other non-language-model values being smuggled in via request context instead of a real provider model instance.

Source

Thrown at packages/agent-builder/src/utils.ts:683

// Helper function to resolve model from request context with AI SDK version detection
export const resolveModel = async ({
  requestContext,
  defaultModel = 'openai/gpt-4.1',
  projectPath,
}: {
  requestContext: RequestContext;
  defaultModel?: MastraLanguageModel | MastraLegacyLanguageModel | string;
  projectPath?: string;
}): Promise<MastraLanguageModel | MastraLegacyLanguageModel> => {
  // First try to get model from request context
  const modelFromContext = requestContext.get('model');
  if (modelFromContext) {
    console.info('Using model from request context');
    // Type check to ensure it's a MastraLanguageModel
    if (isValidMastraLanguageModel(modelFromContext)) {
      return modelFromContext;
    }
    throw new Error(
      'Invalid model provided. Model must be a MastraLanguageModel instance (e.g., openai("gpt-4"), anthropic("claude-3-5-sonnet"), etc.)',
    );
  }

  // Check for selected model info in request context
  const selectedModel = requestContext.get('selectedModel') as { provider: string; modelId: string } | undefined;
  if (selectedModel?.provider && selectedModel?.modelId && projectPath) {
    console.info(`Resolving selected model: ${selectedModel.provider}/${selectedModel.modelId}`);

    // Detect AI SDK version from project
    const version = await detectAISDKVersion(projectPath);

    // Create model instance with detected version
    const modelInstance = await createModelInstance(selectedModel.provider, selectedModel.modelId, version);
    if (modelInstance) {
      // Store resolved model back in context for other steps to use
      requestContext.set('model', modelInstance);
      return modelInstance;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Instantiate the model with a provider factory before putting it in context, e.g. openai('gpt-4') from @ai-sdk/openai
2. If the model arrives as a string/id, resolve it server-side: a registry map from {provider, modelId} to a constructed MastraLanguageModel
3. Do not serialize/deserialize model objects across boundaries (HTTP, JSON) — reconstruct them from identifiers on the server
4. Check that the AI SDK provider package versions are compatible so isValidMastraLanguageModel recognizes the instance

Example fix

// before
requestContext.set('model', 'openai/gpt-4');

// after
import { openai } from '@ai-sdk/openai';
requestContext.set('model', openai('gpt-4'));

function isMastraLanguageModel(m: unknown): m is MastraLanguageModel {
  return (
    !!m &&
    typeof m === 'object' &&
    typeof (m as any).doGenerate === 'function' &&
    typeof (m as any).doStream === 'function'
  );
}
// usage
if (!isMastraLanguageModel(candidate)) throw new Error('Provide openai("gpt-4")-style instance, not a string');

When it happens

Trigger: Setting requestContext 'model' (or the context key the builder reads) to a string like 'openai/gpt-4', a serializable model descriptor object, or any value that is not produced by a provider factory (openai('gpt-4'), anthropic('claude-3-5-sonnet'), etc.).

Common situations: Passing model names from API payloads/UI directly into context instead of instantiating them with the provider SDK; JSON-deserialized model objects losing their class identity; config files storing model ids as strings; version changes in AI SDK model types breaking the validator.

Related errors

• Plugin entry must be a .ts file
• INVALID_AGENT_SCORERS
• Invalid model configuration provided
• observationalMemory.experimental_subconscious must be a Subc
• AcpAgent does not support resuming suspended generate calls

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